Documentation workflow

From TYPO3Wiki

<< Back to About the Documentation page   (edit)

Documentation workflow

Here is the workflow to follow when adding new content to an existing manual or writing a completely new manual/article/tutorial for TYPO3 on this wiki. If you start from scratch, you can use the template made for extension documentation.

Document to discuss

• First you should see if there is a need/interest for the document. Direct your question to the documentation news group.
• Then you should decide under which section you should put a link to the document. Then ask the DocTeam to put up the link and make the new page. It is not forbidden to make the link and page yourself, but it is considered good practice to ask first.
• The new document should be put under the Documents in progress section.

First drafts (from authors)

• Start with brief description – what does this document aim to do; what does it assume; who is it for?
• Write in StarOffice or OpenOffice using headers starting at level 2
• Use file-name format T3MAN_descriptive-name
• Use [ADD: description-of-diagram] to insert diagrams
• Use [Fig: XX description] to refer to diagrams
• Do not include screenshots yet; only include diagrams when absolutely necessary

First review

To determine usefulness and context in existing documentation

• What level of expertise does this document assume – change if necessary
• If document is worth publishing add figures, diagrams and inserts
• Include document in whole manual – include references to other sections

Second review

As first review – for consensus

• Secondary reader to check usefulness
• Collect comments

Final editorial

To make presentable

• Finalise figures, screen-shots and diagrams
• Finalise references
• Finalise grammar and spelling
• Include in main manual file

Publish

• Write short blurb and attach as abstract
• Publish blurb to the mailing lists
• Publish as chapter in TYPO3 documentation repository (html)
• Publish as OpenOffice document and PDF file.