Style Guide für die Dokumentation

Style Guide Regel #1: Beachte den Style Guide. Regel #2: Siehe Regel #1.

TL;DR? Das machen wir hier nicht!

Diese Seite kann man nicht zusammenfassen. Der Style Guide muss komplett gelesen und befolgt werden. Abweichungen vom Style Guide sollten nur nach vorheriger Diskussion passieren, um den Style Guide entsprechend der praktischen Anforderungen zu verändern.

Durch die Verwendung eines Style Guides erscheint das Dokumentationsportal dem Leser in einheitlicher Struktur und Design. Ohne einen Style Guide müssten unsere Leser ihre Erwartungen entsprechend jedem Dokument neu anpassen. Das wiederum würde zu einer weniger idealen Leseerfahrung mit möglichen, unnötigen Fehlern und Versäumnissen führen.

Generelle Richlinien

• Versuche so wenige Wörter zu verwenden wie möglich und dabei Deine Erklärungen trotzdem ausreichend zu beschreiben.

• Sei konkret und lass wichtige Informationen und Überlegungen, die einer fundierten Entscheidung des Lesers zu Gute kommen könnten, nicht weg

• Schreibe Schlüsselwörter für Benutzerhandlungen in Deinen Anweisungen fett gedruckt (Beispiel: Öffne Chrome, klicke oben in die Adresszeile und schreibe dort www.ether1.org hinein)

• Benutze kursiven Text für Namen und Kurzreferenzen/Zitate

• Benutze so viele Screenshots, wie möglich, um Deine Informationen so weit wie möglich visuell zu ergänzen und füge sie mit Deinen Anweisungen zu den Benutzerhandlungen in Fettdruck zusammen (siehe vorherige Richtlinie)

• Benutze dreifache Code Tags um zwischen Terminal Kommandos, Texteditor Inhalten und Code Blöcken zu unterscheiden

• Benutze einfache Code Tags um alles andere hervorzuheben, was Du für nötig hälst

• Benutze Block-Zitate für Notizen, Kommentare und längere Zitate/Referenzen

Titel, Überschriften und Zusammenfassungen

• Jedes nicht verbindende (es sei denn es wird als erstes Wort des Titels verwendet) Wort des Titels wird groß geschrieben (Beispiel: Dies ist ein Beispiel Titel)

• Jedes Dokument beginnt mit einer Zusammenfassung, Einleitung oder mit einer Beschreibung, in der der Hintergrund des Dokuments und/oder der Kerninhalt erklärt werden. Die meisten Leute lesen nur diesen Bereich. Daher sollte er umso besser sein.

• Überschriften beginnen beim #/1. Grad

• Unterteile Deinen Inhalt in logische, kleinere Unterteile mit Überschrifen 2. und 3. Grades, um dem Leser zu helfen durch den Inhalt zu navigieren und nützliche Informationen schnell zu finden

Links

• Wann immer Du in diesem Dokumentations Portal etwas referenzierst, schliesse zur einfachen Handhabung immer den Link mit ein

• Benutze gute und sinnvolle Beschreibungen für Deine Links

• Wenn Du Dir mal nicht sicher bist, verlinke zum Nutzen des Lesers