Prosa schreiben
Diese Regeln gelten für Markdown-Dokumentationen und für Doc-Kommentare in Code, in jeder Sprache. Mit „nur Markdown“ gekennzeichnete Regeln gelten nicht für Doc-Kommentare. In diesen Bereichen folgen Doc-Kommentare den Konventionen ihrer Sprache, wie z. B. Go's [Name]-Doc-Links. Skills für bestimmte Dokumenttypen, wie ADRs und Glossare, fügen diesen Regeln eigene Regeln hinzu.
Tonfall
Locker, aber präzise. Schreiben Sie wie ein erfahrener Ingenieur, der einem anderen Ingenieur das Thema erklärt. Vermeiden Sie übermäßig formelle Spezifikationssprache. Bevorzugen Sie klare, natürliche Erklärungen, die technisch korrekt bleiben. Der Tonfall sollte zugänglich und gesprächig, aber nicht salopp sein.
Gehen Sie davon aus, dass die Leser ein mittleres Verständnis der Softwareentwicklung haben, aber möglicherweise weder Dogmatiq-Projekte noch die Domäne des Dokuments kennen. Vermeiden Sie Fachjargon und erklären Sie alle technischen Begriffe, die das Dokument benötigt. Stellen Sie sich den Leser als einen Anwendungsentwickler mit etwa fünf Jahren Berufserfahrung vor, der Go beherrscht, aber wenig Hintergrund in Algorithmen oder Mathematik hat.
Dateinamen (nur Markdown)
Verwenden Sie Kleinbuchstaben für Dateinamen, wie z. B. glossary.md, es sei denn, eine externe Konvention schreibt etwas anderes vor, wie z. B. LICENSE oder README.md.
Zeilenumbrüche (nur Markdown)
Brechen Sie jeden Absatz so um, dass jede Zeile so viele Wörter wie möglich innerhalb von 80 Zeichen unterbringt.
Zeichensetzung
- Verwenden Sie in Prosa gerade Anführungszeichen und Apostrophe (
",'), niemals geschwungene. Nicht-ASCII-Zeichen sind in Codeblöcken und Formeln in Ordnung. - Schreiben Sie Gedankenstriche mit einem Leerzeichen auf jeder Seite, wie in
Wort — Wort. - Verwenden Sie einen Gedankenstrich, nicht Bindestriche, als parenthetischen Trenner.
- Verwenden Sie einen Gedankenstrich für eine Apposition, die einen Begriff definiert, in Listen und in Absätzen. Verwenden Sie hierfür keine Doppelpunkte, Semikola oder Klammern.
- Ziehen Sie in Betracht, Sätze oder Absätze umzustrukturieren, die viele Gedankenstriche enthalten.
- Verwenden Sie Semikola sparsam, für Kontrast (A; B tut das nicht), Einschränkung (A; jedoch B) oder logische Konsequenz (A; daher B). Bevorzugen Sie einen Punkt, wenn die Klauseln natürlich als zwei separate Sätze gelesen werden.
- Ersetzen Sie einen doppelten Bindestrich (
--) in Prosa, wo angemessen, durch einen Gedankenstrich. Schlagen Sie andernfalls die korrekte Zeichensetzung vor.
Rechtschreibung
Verwenden Sie US-Englisch. Folgen Sie im Zweifelsfall go.dev, der Dokumentation der Go-Standardbibliothek oder der AWS- und GCP-Dokumentation.
| US (korrekt) | Nicht US (inkorrekt) |
|---|---|
| analyze | analyse |
| behavior | behaviour |
| canceled | cancelled |
| center | centre |
| color | colour |
| initialize | initialise |
| labeled | labelled |
| serialize | serialise |
Referenzlinks (nur Markdown)
- Verwenden Sie Referenzlinks, niemals Inline-Links.
- Platzieren Sie die Linkdefinitionen am Ende der Datei, in Gruppen, die jeweils mit einem beschriftenden HTML-Kommentar beginnen, wie z. B.
<!-- references -->oder<!-- anchors -->. - Sortieren Sie jede Gruppe alphabetisch nach Bezeichnung. Ausnahme sind die Versionslinks in einer
CHANGELOG.md, die in aufsteigender Versionsreihenfolge bleiben, sodass[0.9.0]vor[0.10.0]kommt. - Wenn ein verlinkter Begriff in pluraler Form vorkommt, fügen Sie eine separate Definition für den Plural hinzu, wie z. B.
[instructions]: #instruction, damit die Quelle natürlich gelesen wird. - Jede Definition muss mindestens einmal verwendet werden. Entfernen Sie ungenutzte Definitionen.
- Jeder Verweis muss eine passende Definition haben. Lassen Sie keine kaputten Verweise zurück.
Überprüfung
Überprüfen Sie den Text anhand jeder obigen Regel. Nennen Sie für jedes Problem den Text, die gebrochene Regel und schlagen Sie eine Korrektur vor.