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

DocTeam/Official Documentation

From TYPO3Wiki
Jump to: navigation, search
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
  • a Git repository on https://git.typo3.org
  • when the documentation was still distributed in extensions:
    • 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: https://forge.typo3.org/projects/typo3cms-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:

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. Reference manuals (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" (overview of the files). See the corresponding Forge project: https://forge.typo3.org/projects/typo3cms-doc-official_template .

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

The official template has been migrated away from OpenOffice and now is in reST format.

Git repository structure on git.typo3.org

The documentation is currently stored in Git repositories: https://git.typo3.org/. See the repositories beginning with "Documentation/TYPO3". From the repository names you can tell the category (see above) and the name of the manual itself. E.g. the repository "Documentation/TYPO3/Reference/CodingGuidelines.git" contains the CodingGuidelines, a reference manual.

Structure per manual

In each repository we hold the manual in English language. It is located in the folder "Documentation". Inside there must be at least one Index.rst file so that you have the following mandatory structure:

|-- Documentation/
    |-- Index.rst

However, for bigger manuals (as ours are) it makes sense to split up the text and to put it into several .rst files in several subfolders. That way we can keep an overview of the bigger structure more easily. So this might also be expanded, e.g. to something like this:

Documentation/TYPO3/Reference/CodingGuidelines.git:
|-- Documentation/
    |-- Index.rst
    |-- Introduction/
       |-- Index.rst
    |-- Chapter 1
        |-- Index.rst
        |-- Subchapter 1.1
           |-- Index.rst
    |-- Chapter 2
       |- Index.rst
    |-- Images/
       |-- (all image files, which are used in this manual)

The Index.rst file in the folder Documentation contains some meta dat, e.g. information about the manual author. It must use the following values (even for translations):

Author: Official Documentation
Email: documentation@typo3.org

We also provide a PDF version of each manual. It is created from the reST files automatically.

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.

Translations for old versions of each manual can still be found in the Git repositories. For the future we still want to store the texts in Git, but we want to use the TYPO3 Translation Server for actually doing the translations. This is still work in progress.


Where do I find more information?

You find information about the Official Documentation here:

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