DocTeam/Official Documentation

This page belongs to the Documentation Team (category DocTeam)

The Documentation Team, with the help of the community, creates and maintains Official Documentation and translations.

What is official documentation?

Official Documentation is all TYPO3 documentation maintained by the Documentation Team. Each piece of documentation is maintained by a specific team. New documentation, or extensively modified versions of existing documentation, go through a peer-review process to ensure high quality. Translations of Official Documentation follow the same review process.

Official documentation can be identified by the following:

• a clear notice displayed on the cover page
• an extension key of the form "doc_core_*", "doc_guide_*" or "doc_tut_*" (see the description of categories below)
  
• usage of a specific icon for the extension encapsulating the documentation

The creation and scope of new documentation is discussed on the documentation mailing list.

Documentation Forge: http://forge.typo3.org/projects/typo3v4-documentation

All official documentation begins with a note that confirms its official nature:

"Official documentation
This document is included as part of the official TYPO3 documentation. It has been approved by the TYPO3 Documentation Team following a peer-review process. The reader should expect the information in this document to be accurate - please report discrepancies to the Documentation Team (documentation@typo3.org). Official documents are kept up-to-date to the best of the Documentation Team's abilities."

Overview of the manuals

Have a look at the Documentation Team page on forge.typo3.org. In the menu on the left you see all the official manuals, which the DocTeam maintains.

Having a look at the target group, these manuals can roughly be divided into the following categories:

1. Introductional documents (e.g. "Getting Started")
2. Editor documents (e.g. "TYPO3 Tutorial for Editors")
3. Administrator documents (e.g. TSref, TSconfig, the "Administrator's Guide" or the "Installation Guide")
4. Developer documents (e.g. the "TYPO3 Skinning Guidelines" or the "TCA Reference")
5. Extension documents

Our job

Our job is the maintenance of these documents. There are two primary tasks:

• Create and update the English version of the documents listed above.
• Create translations of English version.

Please see the maintenance matrix to learn who is working on specific docuentation and which are currently orphaned.

You want to help us?

That is great! We always need helping hands! If you want to participate, please contact us:

• Send us an e-mail or
• Tell us what you want to do in our newsgroup "typo3.projects.documentation"

Official documentation categories

By the style how the different manuals explain things, all official manuals are divided into three categories, that correspond to the three types of extension keys listed above.

The definitions below are printed on the cover page of every manual (according to its type) so that it is clear to the reader what kind of manual he/she is reading.

1. Core manuals:
   This document is a Core Manual. Core Manuals address the built in functionality of TYPO3 and are designed to provide the reader with in-depth information. Each Core Manual addresses a particular process or function and how it is implemented within the TYPO3 source code. These may include information on available APIs, specific configuration options, etc.
   Core Manuals are written as reference manuals. The reader should rely on the Table of Contents to identify what particular section will best address the task at hand.
2. Guides:
   This document is a Guide. Guides are designed to familiarize a reader with a specific topic in order to provide a working knowledge of that particular process. Readers should peruse the guide from cover to cover in order to gain a practical overview of the process. Once completed, the Guide becomes a practical reference tool that a reader will refer to as needed. Guides offer advice on how best to achieve a given task.
3. Tutorials:
   This document is a Tutorial. Tutorials are designed to be step-by-step instructions specifically created to walk a beginner through a particular task from beginning to end. To facilitate effective learning, Tutorials provide examples to illustrate the subjects they cover. In addition, Tutorials provide guidance on how to avoid common pitfalls and highlight key concepts that should be remembered for future reference.

Thanks to Bill Tenny-Brittian for his help on defining and explaining the categories.

Official translations of these categories are available.

Document structure & Official template

All official manuals follow the same structure in terms of cover page, mandatory chapters and sections, etc. The structure is defined by the "Official Documentation Template" (view as PDF). See the corresponding Forge project: http://forge.typo3.org/projects/typo3v4-official_template .

All official manuals must use the new Official template. Read more about how to use the template.

The official template is currently in OpenOffice format. This will be replaced as part of the ReST migration project.

SVN repository structure

The documentation is currently stored in a SVN repository: https://svn.typo3.org/TYPO3v4/Documentation/

The repository is further sub-divided per extension key (each manual is encapsulated in an extension), then come the tags, branches and trunk folders. The next level separates the languages. The extension key is repeated, as is for English, followed by "_" and the language 2-letter ISO code for other languages.

It is not as difficult as you might think right now. As an example here is the structure for the "TypoScript in 45 minutes" tutorial:

+ TYPO3v4/Documentation/doc_tut_ts45/
|
+---+ tags
+---+ branches
+---+ trunk
    |
    +---+ doc_tut_ts45
    +---+ doc_tut_ts45_da
    +---+ doc_tut_ts45_de
    +---+ doc_tut_ts45_it
    +---+ doc_tut_ts45_nl
    +---+ doc_tut_ts45_ru

Extension structure

Each manual and each translation is encapsulated in an own extension. Extension keys follow the naming convention described above, followed by "_" and the language 2-letter ISO code for languages other than English (as seen in the tree view above).

All extensions must use the same icon.

The ext_emconf.php must use the following values (even for translations):

'author' => 'Official Documentation',
'author_email' => 'documentation@typo3.org',

As with all other extensions, the manual itself is placed in the "doc" folder as must be named "manual.sxw" (also for translations).

We must also provide a PDF version of the manual. This is normally named using the extension key + ".pdf".

The "doc/" must also contain a plain text version (named using the extension key + ".txt"), which used for versioning (see the work process details).

Translations

Official documents also have official translations. The translations follow most of the same rules, including the peer-review process. There are specific instructions for translators.

Where do I find more information?

You find information about the Official Documentation here:

• In the Documentation Mailing List on lists.typo3.org.
• In the Bugtrackers on Forge. Select the manual you are interested in and click on "Issues".
• Here in the Wiki with the Category:Official_Documentation.

• Additionally much of our comunication is done personally via e-mail, skype...