Dokumentation als Code #

Diese Seite richtet sich an Ingenieure, die mit ihrer Änderung Dokumentation schreiben oder die Dokumentation einer Erweiterung pflegen. In Exponential liegt die Dokumentation im Repository, wird im selben Pull-Request wie der Code geprüft, von einem Befehl kontrolliert und im Produkt gelesen. Die Funktionsseite ist Das Hilfesystem.

Inhalt #

1. Wo die Dokumentation liegt
2. Wie sie ausgeliefert wird
3. Front Matter
4. Seiten prüfen
5. Dokumentation von Erweiterungen
6. Schreibregeln
7. Lizenz

Wo die Dokumentation liegt #

Wie sie ausgeliefert wird #

Das Hilfesystem zeigt jede von Git verfolgte Markdown- und Textdatei unter doc/ in der Administration (/exphelp/viewer/<path>), mit Überschriften, Inhaltsverzeichnis, Tabellen, hervorgehobenem Code, der Navigation ihres Abschnitts und einem Link auf die Datei bei GitHub; eine Suche findet Seiten nach Titel, Überschriften und Text, mit Filtern für Zielgruppe, Kategorie und Typ. Zum Lesen der Hilfe braucht man die Richtlinie exphelp/read. Eine Datei, die Git nicht verfolgt, ist keine Seite; eine neue Seite erscheint also in der Hilfe, sobald sie committet ist.

Front Matter #

Hilfeseiten beginnen mit einem Block im YAML-Stil:

Seiten prüfen #

./console exp:help check --below=help/software-engineers/   # links and images of the pages below a path
./console exp:help search "clear cache"                      # what readers will find
./console exp:help show guides/caches.md                     # the metadata and headings of one page
./console exp:help index --rebuild                           # rebuild the index

Die Prüfung meldet Fehler (ein Link auf eine fehlende Datei, ein Link, der die Installation verlässt, ein unsicheres Schema, ein defektes Bild), Warnungen (ein Anker, den keine Überschrift hat, ein absoluter Link) und Hinweise (ein Link auf eine Datei, die keine Hilfeseite ist). --strict lässt auch Warnungen scheitern. Verwenden Sie nur relative Links, und verlinken Sie Anker auf Überschriften, die es gibt.

Dokumentation von Erweiterungen #

Die Hilfe zeigt die Dokumentation, die jede aktive Erweiterung mitbringt (ihr Verzeichnis doc/, README, CHANGELOG, LICENSE), unter /exphelp/extensions, im selben Betrachter und in derselben Suche (Hilfesystem für Erweiterungen, Ihre Erweiterung dokumentieren). Die Konvention ist dieselbe Dokumentation als Code: README.md und INSTALL.md oben in extension/<name>/, jede weitere Seite als Markdown (.md) in extension/<name>/doc/, auf Englisch (Eine Extension dokumentieren).

Schreibregeln #

• Schreiben Sie, was es gibt. Prüfen Sie jede Aussage im Code, in den Einstellungen oder auf einer anderen Seite, und sagen Sie es, wo die Quellen keine Antwort geben.
• Nennen Sie das Produkt Exponential. Bezeichner wie eZContentObject bleiben, wie sie sind; der alte Produktname erscheint nur als Geschichte.
• Nur echte Befehle in Codeblöcken; keine Hostnamen, Konten oder Passwörter einer echten Installation.
• Amerikanisches Englisch in der Oberfläche und der englischen Dokumentation.
• Eine Verhaltensänderung erhält ihren Upgrade-Hinweis, eine Funktion ihre Seite, ein Release sein Changelog (Changelogs und Upgrade-Hinweise).

Hilfethemen, die als Inhalte in der Administration gepflegt werden, folgen ihrem eigenen Stilleitfaden und ihren Prüfzuständen (Stilleitfaden der Hilfe, Die Hilfe aktuell halten).

Lizenz #

Die Dokumentation ist frei unter der GNU Free Documentation License 1.3; der Code steht unter der GNU GPL, Version 2 oder später (Freie Dokumentation, Standards für Dokumentation und Veröffentlichung).

Verwandte Seiten #

• Das Hilfesystem
• Standards der Hilfe
• Beiträge an das Projekt
• Freie Dokumentation: Diese Seite darf unter der GNU FDL 1.3 frei kopiert, übersetzt und verbessert werden.