Conversation
…guide, move info from language to index
leiascyr
left a comment
leiascyr
left a comment
There was a problem hiding this comment.
minor fixes of some articles, major changes to be discussed
| # Contributing to the docs | ||
|
|
||
| This section of the documentation explains how the documentation itself works, how we wrote it, and how to contribute to it. | ||
| If you want to contribute to the pretix documentation, then you should read this article and the following articles: |
There was a problem hiding this comment.
If you want to contribute to the pretix documentation, then you should read this article and the following articles:
Hier fehlt gefühlt die Hälfte der Punkte, über die wir gesprochen hatten, wie man zur Doku beitragen kann. Wir sollten noch mal über die Zielsetzung sprechen.
| This section of the documentation explains how the documentation itself works, how we wrote it, and how to contribute to it. | ||
| If you want to contribute to the pretix documentation, then you should read this article and the following articles: | ||
|
|
||
| - You can find information on how to set up your development environment under [Development environment](development-environment.md). |
There was a problem hiding this comment.
- You can find information on how to set up your development environment under Development environment.
Das ist hier eher kontextlos. Eine Problemstellung, die vermutlich aus den o.g. anderen fehlenden Punkten folgt.
|
|
||
| - You can find information on how to contribute an article to the pretix docs under [Adding a guide](adding-a-guide.md). | ||
|
|
||
| - You can find information on terminology, orthography, and punctuation under [Language](language.md). |
There was a problem hiding this comment.
- You can find information on terminology, orthography, and punctuation under Language.
- You can find information on how to format your text using Markdown, MkDocs, and our customizations under Formatting.
Beides nur relevant als Unterpunkte für "contribute an article", oder?
There was a problem hiding this comment.
Das ist auch für kleinere Beiträge relevant, z.B. Reviews, Übersetzungen oder das Hinzufügen einzelner Unterabschnitte. In jedem Fall ist es wichtig dafür, zu verstehen, wie die Doku als ganzes funktioniert
|
|
||
| ## How to | ||
|
|
||
| This article describes [best practices](#best-practices-what-to-do-when-writing-documentation-for-pretix) as well as [what not to do](#what-not-to-do-when-writing-documentation-for-pretix) when contributing to the docs. |
There was a problem hiding this comment.
This article describes best practices as well as what not to do when contributing to the docs.
Grundsatzfrage, s.o.
| Hearing the link text "here" five times in a row is **not** very informative. | ||
| Even without a screen reader, it helpful for the reader if they have a general idea what is behind the link. | ||
|
|
||
| MkDocs uses different symbols to precede internal and external links in the documentation visible to readers to make it easier to distinguish between them. |
There was a problem hiding this comment.
MkDocs uses different symbols to precede internal and external links in the documentation visible to readers to make it easier to distinguish between them.
More accurately, one symbol precedes internal links while external links are followed by a different symbol.
| MkDocs uses different symbols to precede internal and external links in the documentation visible to readers to make it easier to distinguish between them. | ||
| You do not have to specify this because it works automatically. | ||
| The formatting for both types of links is "link text in square brackets, URL/path in round brackets". | ||
| Insert cross references to a subheading within another (or the same) article work as follows: |
There was a problem hiding this comment.
Insert cross references to a subheading within another (or the same) article work as follows:
After verbally describing the rest of the link formatting, why omit this last element from the description?
2 participants
How to contribute