DocTeam/Official Documentation Work Processes
This page explains how we do our documentation work.
To be able to edit a manual, you must be member in that manual's project on forge.typo3.org.
- Changing the RST files (for details see reST)
- We use American English.
- In some documents (like TSconfig or TSref) you maybe have to add or change properties:
- If a property became deprecated, add a corresponding note at the end of its description.
- If a property was removed, also add a corresponding note at the end of its description. We *do not delete* removed properties from the documentation. That way, users can more easily work with one manual version for all TYPO3 versions.
- Save the files
- Commit, using a concise commit message. Then push to the Gerrit review server (for details see one of our walkthrough tutorials).
- For information on restructuring a manual, which has newly been migrated to reST see here.
- when a new patch set has been pushed to the Gerrit review server, a review takes place
- any member of the official documentation team can perform the review and vote
- a single positive vote is enough (two votes would be desirable in the future, as the team expands (hopefully))
- translations are reviewed by native speakers
- if the manual is about a specific area (e.g. security) it should be reviewed by an expert in that area (e.g. a member of the Security Team)
- the reviewer is encouraged to perform changes directly, except if he/she feels like discussions is warranted. After changes he should upload a new Patch Set.
A release is made by creating a tag in the Git repository.
- the tag name should be/look like ...
There are currently two numbering schemes:
- primary core reference documents (doc_core_tsref, doc_core_tsconfig, doc_core_ts, doc_core_api) follow the major version number of TYPO3 (4.2, 4.3, etc.) and used their own minor version numbers (i.e. 4.3.1, 4.3.2, etc.) for each of their own revisions between two major versions of TYPO3. The minor version numbers of documents don't follow the minor version numbers of TYPO3.
- secondary core documents, like doc_core_services are mostly independent of TYPO3 versions and follow their own numbering scheme. It's up to the document's author to decide which number they increase upon each new release.
- unless there are reasons for an early release, a new document should be released only when a satisfying first version has been written. The first release should thus normally be version 1.0 and have a "stable" status.
Old release process
The following information was used, when the documentation was still delivered in extensions. It was then only important for you if you wanted to release a manual to TER.
Checklist of the steps to release a new version of a manual:
- Update the version number on the cover page
- Update section "What's new"
- Update the table of contents in the OpenOffice.org document
- Regenerate the TXT version (Save as... > Text (coded) >> Charset UTF-8, Line endings LF, UNIX)
- Regenerate the PDF file using the PDF button in the main toolbar. This gives the best results. In particular, it generates clickable items in the table of contents.
- Update the ChangeLog file (including the release)
- Put folder with these extension files into typo3conf/ext/
- From inside TYPO3 (Extension Manager):
- Update array in ext_emconf
- Release the extension, choosing an appropriate incrementation of the version number (see below)
- There can be problems because of the size of the extension (can happen with Getting Started and TSref). If uploading fails because of the size, release without the PDF file.
- Take the modified ext_emconf file and commit all the changed files to SVN.
- Add the released version to the wiki page Documentation Update Process.
This list is an important guideline for working on a manual. Most of the points are mentioned elsewhere too, but this provides a convenient checklist.
- The proper extension key prefix: doc_core, doc_tut, doc_guide
- The layout of official_template (with TYPO3 logo on top left)
- E.g. correct styles for enumerations ("List" style)
- No broken links
- No TypoScript errors
- Screenshots of the current major version of TYPO3 (4.x)
- Section "Next steps" with links to other official manuals. Even better: Mention where in the document the information can be found (chapter and section) as the order of chapters and sections and with them the URLs can change (this also prevents old versions from being linked).
- English proofread and edited by a native speaker
- No typographic errors (use a spellchecker)