Formatierung von Dokumentationsdateien

Empfehlungen

Editoren ohne Autoformatierung verwenden

Für die Bearbeitung der Dokumentation sollten typischerweise keine formale XML Editoren verwendet werden. Solche Editoren formatieren bestehende Dokumente normalerweise so das diese Ihren eigenen Standards folgen und folgen dem Docbook Standard nicht strikt. Als Beispiel haben wir gesehen das Sie die CDATA Tags entfernen, die Trennung von 4 Leerzeichen zu Tabs oder 2 Leerzeichen ändern, usw.

Die Styling Richtlinien wurde großteile geschrieben um Übersetzern zu helfen damit diese durch Verwendung von normalen diff Tools erkennen welche Zeilen sich geändert haben. Die Automatische formatierung macht diesen Prozess viel schwieriger.

Verwendung von Bildern

Gute Bilder und Diagramme können die Lesbarkeit und Gemeinsamkeit erhöhen. Sie sollten immer dann verwendet werden wenn Sie diesen Zielen helfen. Bilder sollten im Verzeichnis documentation/manual/en/figures/ platziert, und nach dem Kapitel benannt werden in dem Sie vorkommen.

Gute Fallbeispiele

Man sollte nach guten Fallbeispielen sehen die von der Community verbreitet werden. Speziell jene die in den Kommentaren der Proposals oder einer der Mailing Listen gesendet werden. Beispiel zeigen oft viel besser die Verwendung als es Beschreibungen tun.

Wenn man Beispiele für die Inkludierung in das Handbuch schreibt, sollte man allen Coding Standards und Dokumentations Standards folgen.

Vermeide die Wiederholung von phpdoc Inhalten

Das Handbuch ist dazu gedacht ein Referenzhandbuch für die Verwendung durch Endbenutzer zu sein. Die Wiederholung von phpdoc Dokumentation für intern verwendete Komponenten und Klassen ist nicht erwünscht, und die Beschreibungen sollten auf die Verwendung fokusiert sein, und nicht der internen Arbeitsweise. In jedem Fall und zu jeder Zeit wollen wir das sich die Dokumentations-Team auf die Übersetzung des englischen Handbuchs und nicht den phpdoc Kommentaren fokusiert.


Formatierung von Dokumentationsdateien