Translations
Info
All page names need to be in English.
en da  de  fr  it  ja  km  nl  ru  zh

Documentation guidelines

From TYPO3Wiki
Jump to: navigation, search

<< Back to Documentation Team   (edit)

How to write documentations; the rules, templates, tips and trix. Also something about why we write documentation in a certain way.

Documentation goals

  • 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. ;-)

Main editor

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:

Web pages about writing

Interesting articles on how to get information distributed:

Books about writing

See also