Basic Principles

Introduction to TYPO3 Documentation

For an excellent introduction, please see the 3 part series on Marcus Schwemer's blog TYPO3 Worx:

Important

Please note that the section "CONVERT REST TO “READABLE” FORMATS" in part 3 is slightly outdated. Currently, using the Docker container for rendering is the recommended approach. If you edit on GitHub directly, GitHub preview should be sufficient for making small changes.

What's TYPO3 Documentation?

TYPO3 documentation may be one of the following:

Common Characteristics of TYPO3 Documentation

All of these examples have a few things in common:

  • The documentation is rendered and found on https://docs.typo3.org
  • The documentation has a common theme, all pages look similar and use the same styles
  • Most of the documentation can be directly edited by the community. For third party extensions, this depends on where and how the source-code is hosted and maintained.
  • The source of the documentation is written (mostly) in reStructuredText (reST)
  • All documentation is rendered using the same rendering toolchain. All documentation can be rendered locally, with the officially supported Docker image.
  • The documentation source files adhere to Conventions and share a common structure (e.g. all documentation files in a Documentation subdirectory).
  • Due to the conventions, the rendering of documentation can be automated and every documentation project only requires a minimum of setup.

What's "Rendering"?

Rendering means (in this specific case) converting the reST format (.rst files) into its final, readable form, which you can view in your browser, like this page, which you are probably reading online. If not, load https://docs.typo3.org/typo3cms/HowToDocument/BasicPrinciples.html in your browser.

In comparison, this is what the original source file looks like: https://docs.typo3.org/typo3cms/HowToDocument/_sources/BasicPrinciples.txt

Technically, this means converting the reST (.rst files) into HTML, automatically creating the menu, using the current theme to add additional styles and images.

Documentation Types

Manual

A "manual" in the context of TYPO3 documentation is being used to talk about one unit of documentation, which usually has it's own git repository (or is included in the git repository of an extension) and consists of one Documentation folder. A "manual" can be a tutorial, such as the Getting Started Tutorial, a guide, an extension manual or something else.

Tutorial

A tutorial is a manual.

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.

Guide

A guide is a manual.

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 to which a reader can refer as needed. Guides offer advice on how best to achieve a given task.

Extension Manual

An extension manual covers only the extension. This documentation is (usually) included in the source code of an extension in a Documentation subdirectory.

Documentation Contribution Matrix

Considering how to contribute, the things that differ for various kinds of documentation are:

  • Where the issues are maintained (e.g. on Forge or GitHub)
  • Where the source code (Git repository) is kept
  • The workflow for making changes to the documentation
Type of documentation Issues Source Code (Git repository) Workflow for making changes
Official guides, tutorials, core docs, etc. On page of rendered docs, click on Related links > Issues On page of rendered docs, click on Related Links > Repository, or click on Edit me on GitHub Create GitHub pull request, see Contribute.
TYPO3 Core Changelog Core issues: https://forge.typo3.org/projects/typo3cms-core/issues TYPO3 source code: git.typo3.org, mirror: GitHub see Contribution Guide: Add documentation
System extensions Core issues: https://forge.typo3.org/projects/typo3cms-core/issues Same as for Changelog, inside TYPO3 source code: git.typo3.org, GitHub as mirror see Contribution Guide: Add documentation
3rdparty extensions On page of rendered docs, click on Related Links > Issues On page of rendered docs, click on Related Links > Repository, see Contribute to Third Party Extension It depends, see Contribute to Third Party Extension

To get to the issues or repository of the documentation: On the page of the rendered manual, click on "Related Links" and then click on "Issues" or "Repository".

_images/related2.png

Official TYPO3 Manuals

The official TYPO3 manuals are hosted on GitHub. Editing the documentation requires a GitHub account and involves creating a pull request on GitHub.

Find out more about how to contribute: Contribute.

Documentation for the Core

The documentation for the core (changelog and system extensions) is added to the TYPO3 source code. For this reason, the workflow of changing something in the core documentation is very similar to adding a patch to the core.

Find out more about the core contribution workflow in general or about Add documentation (Changelog etc.) in the Contribution Guide.

Documentation for 3rdparty Extensions

The documentation for a 3rdparty extension is maintained within the source-code of this extensions. If and where it is edited depends on where the extension is hosted and maintained.

To find out how to contribute documentation for a specific extension: Contribute to Third Party Extension

What about the Wiki?

In this manual, we are focusing on TYPO3 documentation in reST / sphinx that can be found on docs.typo3.org.

The TYPO3 Wiki on https://wiki.typo3.org does contain documentation as well, but that is not the scope of this manual. In any case, most of the information from the Wiki is being moved from the Wiki to some manual on docs.typo3.org.