- Readability: A TYPO3 document should be easy to read and easy to understand. It should be concise, allowing the reader to get the most information in a short amount of time. Use few words!
- Accessability: A TYPO3 documentation should be understood by more than just administrators and developers. Newbies, though they have to bring some knowledge about web technologies with them, should find an easy access to TYPO3 thanks to the documentations.
- Structure: The structure of TYPO3 documentation should make it easy to find information. The overall structure (the structure amonge all documentations) should be problem oriented. The internal structure (inside each document) should be tutorial oriented. Referencial documentation cannot and shouldn't follow those guidlines though they should still be structured.
The TYPO3 name
Please be aware that TYPO3 should be written fully capitalized. The exception is for domain name or URL which can be written in lowercase. So
- TYPO3 is the product name
- typo3.org in the url
Any other TYPO should be avoided. ;-)
For pages/documents under progress, we like to have a main editor. That would be someone who could keep an eye on the project and report its status to the documentation mailing list/news group. Beeing a main editor DOES NOT mean that you have to do all the work, but it is assumed that you take some part of it. Still, the main thing is that you manage the project:
- engage people to write different parts of the document
- report status to the mailing list
- decide the status on the document
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:
- Document template for extensions. (PDF, SXW and TXT format only. Not compatible with Sphinx.)
- The same extension template, but for the wiki.
- 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/-/0321965515/