Let’s team up: How agencies can successfully work with a TYPO3 tech partner
Creative agencies often lead with strong concepts and design, but TYPO3 projects also demand reliable technical execution. This guest article explores…
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.
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.
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.
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.
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:
Creative agencies often lead with strong concepts and design, but TYPO3 projects also demand reliable technical execution. This guest article explores…
Starting November 1, 2025, TYPO3 v11.5 enters its second year of Extended Long-Term Support (ELTS). If your organization depends on this version, now…
Awards season is here, with the TYPO3 Awards 2025 nominees announced ahead of the Düsseldorf gala, while members selected four new ideas to fund in Q4…
New ELTS pricing for TYPO3 v12 starting April 2026, with membership discounts unchanged and early notice to support planning. No changes for v11 and…
Discover the 2025 TYPO3 Awards nominees across 17 categories. Join us in Düsseldorf on November 27 for the gala celebrating the year’s top TYPO3…
Each month, we celebrate TYPO3 contributors in our Developer Appreciation Day post. Please take a moment to share gratitude for their continued…