Standardization of TYPO3 Documentation—May 2022

In the past, creating full documentation for a TYPO3 project often started with copying and adapting the basic file structure of an existing set of documentation. Since creating documentation is not part of the daily business for most developers, the adaptation regularly led to confusion, and subsequently to a best-guess adaptation that lost quality with each copy made.

Remember the questions you had when a description of your project was required in each of the README, Settings.cfg, and Index.rst files? Or when you wondered about the Classification field in the Index.rst that usually contained the extension key, the Keywords field that seemed quite old-fashioned, or the rather superfluous TYPO3 project slogan that took up most of the Index.rst content space? The redundant setting of the Home and Repository links in the footer of the documentation to the code repository URL was just another symptom of an overwhelmed occasional documentation writer with too many options available, but no guide to light the way.

So, in October 2021, the Documentation Team started a process that resulted in a revised documentation standard that guides the writer in creating the right base files and content. We reviewed each documentation theme parameter and text component for relevance, and scanned a large number of live projects to develop an accurate description and value recommendation. In addition, the standard provides a template for each base file that can be copied into your own project. Last but not least, the multipliers of the documentation standard, such as the Example Manual and the ReST Helper, have been adapted accordingly. The Extension Builder, as another multiplier, will also adopt the standard if the associated budget request is approved.

As a by-product, the new User’s Round Trip guide was created to help intuitively guide and sign-post the user to the other aspects of the project.

The new TYPO3 documentation standard follows the idea of a scientific paper.

Now that this standard has been developed and applied to the official TYPO3 ELTS manuals, TYPO3 LTS system extension documentation, and selected third-party extensions for the latest release, it is ready for a full rollout to the TYPO3 community. Feel encouraged to apply it to your projects in the TYPO3 ecosystem to bring documentation up to an industry standard and quickly guide your users through all aspects of your project.

This is another piece of our strategy to establish a splendid global documentation of the TYPO3 ecosystem on docs.typo3.org.

Contact the team in our Slack channel #typo3-documentation anytime if you have questions about the standard.

Skål fra dokumentationsteamet!

In short:

• Work: around 310 hours
• See: Revised documentation standard
• See: User's Round Trip guide
• See: Revised 252 official manuals
• See: Revised 56 third-party manuals