Professional Content Management

Free and open source, TYPO3 CMS is the most widely used enterprise-level CMS.

Test TYPO3 now:

TYPO3 live demo

Inspire people to share

Offer your skills and contribute to the project. The community is growing and does more than just coding. 

A Community Effort

TYPO3 CMS is an Open Source project managed by the TYPO3 Association.

The Project

Do you have a question?

Ask the community or a professional partner.

Standardization of TYPO3 Documentation—May 2022

Categories: Development, Community Created by Alexander Nitsche
To help foster distribution and contribution for your TYPO3 extension, Composer package, or standalone manual, apply the revised TYPO3 documentation standards to your project. Also, create a user navigation that conveniently navigates between your project’s documentation, code repository, Packagist and TER pages by following our new guide.

Background

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 Revised Documentation Standard

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

Full Documentation

The index page of the full documentation contains the title, some important metadata (extension key, package name, license, etc.), the abstract and the table of contents (TOC) to give the decision makers a good grasp of the scope of the project. Once interest is gained, they can quickly read through the full documentation.

The project title does not need to contain the keyword “TYPO3”, as the context is obvious. It is important that the TOC is displayed in the content area, which might seem superfluous for desktop views (where the menu is always visible), but is valuable for mobile views where it is collapsed by default. In addition to the main menu, the visually-separated meta menu always provides two technical pages: the sitemap and the index, both of which are automatically created from the documentation content.

Index page of full documentation

README of Code Repository

As a close companion to the full documentation, the home page of the code repository, the README file, serves as the entry page to the documentation. It should contain statistics, the abstract and a link to the full documentation.

The title should announce the TYPO3-specific context, for example by the pattern “TYPO3 extension <extension-key>”. The usual badges should be used to display store statistics and TYPO3 compatibility. It is important not to use this page for additional documentation—it is intended to provide a snapshot of distilled information about the project deduced from the full documentation and store statistics. It should not be an additional burden on the documenter’s shoulders, nor cause confusion for the reader.

Home page of code repository

The User's Round Trip

A round trip, set up using the new User’s Round Trip guide, conveniently routes the reader or project user through all aspects of a project using native configuration settings.

User's round trip
  • To redirect the user from the full documentation to other aspects, configure Settings.cfg and see the links in the footer of the documentation pages (see full documentation screenshot above).
  • To redirect the user from the code repository to other aspects, add a table of links to the README file that will be displayed on the code repository home page (see code repository screenshot above).
  • To redirect the user from Packagist to other aspects, configure the composer.json file and see the rendered links in the right column of the Packagist project page.
  • To redirect the user from TER to other aspects, configure the extensions management page and see the rendered links in the right column of the TER project page.
Project page on Packagist
Project page on TER

Conclusion

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:

Additional contributors for this article
  • Copy Editor : Mathias Bolt Lesniak

Latest news

Show more