De:Documentation guidelines
<< zurück zu De:About the Documentation
Wie man Dokumentationen schreibt, Regeln, Vorlagen, Tipps und Tricks. Und ein bisschen darüber, warum die Dokumentation in einer bestimmten Art und Weise geschrieben wird. |
||
Bitte nur auf der Spielwiese üben! |
Ziele der Dokumentation
- Lesbarkeit:
Eine TYPO3-Dokumentation sollte leicht zu lesen und zu verstehen sein. Sie sollte kurz und bündig sein, damit der Leser das größtmögliche Wissen in der kürzest möglichen Zeit erfahren kann. Benutzt also wenige Worte!! - Verständlichkeit:
Eine TYPO3-Dokumentation sollte von mehr Menschen als nur von Administratoren und Entwicklern verstanden werden. Neulinge, auch wenn sie nur ein wenig Kenntnisse über Web-Technologien mitbringen, sollten durch die Dokumentation einen leichten Zugang zu TYPO3 erlangen. - Struktur
Die Strukturierung der TYPO3-Dokumentation sollte das Auffinden von Informationen vereinfachen. Die Gesamtstruktur (also die, die sich durch alle Dokumentationen zieht) sollte problemorientiert sein. Die interne Struktur eines Dokuments sollte lernorientiert sein. Referencial documentation (???) kann und soll diesen Richtlinien nicht folgen, obwohl auch sie strukturiert sein sollten.
Der Typo3 Name
Es ist darauf zu achten , dass TYPO3 komplett groß geschrieben wird. Die einzige Ausnahme ist für Domainnamen oder URLs erlaubt, hier sind Kleinbuchstaben erlaubt. Also
- TYPO3 ist der Produktname
- typo3.org in einer URL
Jedes ander TyPO3 sollte vermieden werden ;-)
"Main Editor"
Für Seiten/Dokumente, die in Bearbeitung sind, wäre es toll, wenn sich ein "Main Editor" finden würde. Das wäre jemand, der das Projekt im Auge behält und seinen Status an die entsprechende Mailingliste/Newsgroup weitergibt. Ein "Main Editor" zu sein, bedeutet nicht, dass er alle Arbeit alleine machen soll, aber er sollte schon einen Teil davon übernehmen. Die Hauptsache ist aber, dass er das Projekt managet:
- Andere sollen ermutigt werden, Teile des Dokuments zu schreiben
- Der Status des Dokuments sollte an die Mailingliste weitergegeben werden
- Den Status des Dokuments bestimmen
Headers in SXW documents
Headers in OOo documents are automatically converted to its HTML eqivalent in the TOC of the documentation library on typo3.org. Headers on the first level (on the web page) is simply achieved with "Heading 1" in the document. BUT please reserve that heading for major sections.
Only very large documents with close to or above hundred pages uses the top level ("Heading 1"). All extension manuals should only use "Heading 2" for major sections down to "Heading 5".
Template and guidelines
The following documents can be useful when writing Typo3 documentation:
- A part of the manual for developers contains info about writing and proofreading documentation.
- If you want to make a video, you have guidelines in the document Creating Video tutorials.
Web pages about writing
Interesting articles on how to get information distributed:
- How Users Read on the Web -> http://www.useit.com/alertbox/9710a.html
- Inverted Pyramids in Cyberspace -> http://www.useit.com/alertbox/9606.html
- 10 Tips on Writing the Living Web -> http://www.alistapart.com/articles/writeliving/
Books about writing
- Hot text -> http://www.amazon.com/exec/obidos/tg/detail/-/0735711518/
- Don't make me think -> http://www.amazon.com/exec/obidos/tg/detail/-/0789723107/
