TYPO3 Documentation Team Report 2021

Categories: Community, Documentation Created by Alexander Nitsche
Credits: Markus Schwarz, iStock.com/IvanNikulin, iStock.com/klyaksun, iStock.com/Nadzeya_Dzivakova
The TYPO3 documentation tools are constantly improved by the TYPO3 Documentation Team to support you, the reader, in getting comprehensive information and quickly finding answers to your questions, and to help you, the author, in creating documentation and to increase the visibility and popularity of your extension in the TYPO3 world.

In this report we will present this year’s improvements to the tools and the official TYPO3 documentation.

Benefits of Writing Documentation

Similar to testing, documentation has a self-healing effect for the developer by reflecting on their own implementation as it is explained, and checking decisions for plausibility. It also increases visibility by giving decision-makers an insight into the product without them having to install and try it out. In addition, the TYPO3 extensions with public documentation can be found via the new global search of docs.typo3.org, which indexes all official documentation manuals as well as the extension documentation, further increasing its visibility and thus its popularity. Last but not least, writing the documentation in reST markup and compiling it with the official TYPO3 Sphinx template provides a defined set of well-designed content elements that improve the clarity and readability of your documentation.

Achievements and Features

In 2021, the documentation team added the following features to the official documentation and tools.

Moving wiki.typo3.org to docs.typo3.org

At the beginning of the year, the rather outdated TYPO3 Wiki instance reached the end of its life. Essential articles were migrated to the official documentation. The main process consisted of reworking the articles, converting the markup from HTML to reST, and redirecting from the old to the new URL.

In addition to the manual process of migrating articles, the wiki also provided exception page management, which allowed TYPO3 users to read community solutions for handling exceptions in the TYPO3 instance. This process of creating, updating and reading these exception pages has been seamlessly migrated to docs.typo3.org - it is now managed via the Edit on GitHub process which forms part of the official TYPO3 documentation workflow.

See also:

Global Search

Providing a powerful and TYPO3-centric search across all official documentation manuals and extension documentation on docs.typo3.org was one of the highlights of this year’s new features. This search function closes the gap between the global search engines and the local search per manual on docs.typo3.org, and provides a powerful search box, a set of filters and well-labeled search results. Whenever you search for a specific TYPO3 term, this place should be your first port of call.

On the other hand, it becomes more valuable for the documentation author to define the terminology precisely and use keywords carefully in order to be high in the search results for specific terms—and to register the extension documentation for publishing at docs.typo3.org, no matter if it is a simple README.md, README.rst or a full reST documentation in the Documentation folder.

See also:

Automatic Screenshots

The official TYPO3 documentation contains almost 850 images, a large part of which are from the TYPO3 installation process, backend and frontend. Since these screenshots are outdated every 1.5 years with each TYPO3 LTS release, documentation maintainers would have to recreate all screenshots at the same frequency, which is not affordable. On the other hand, TYPO3 has integrated acceptance testing for many years with the support of the Codeception framework, and this framework has a built-in screenshot feature that is mainly used to gain insight into acceptance tests during debugging.

The documentation team was given a budget this year to manually re-create documentation screenshots once, but instead of doing this in the traditional way, they started the TYPO3 Screenshots project to script photo tours of TYPO3 that—like tests—can be run repeatedly and customized granularly to reduce large portions of maintenance costs in the future. The project provides several TYPO3 environments, called suites, consisting of the TYPO3 Core and optionally a pre-installed distribution, which are walkable by scripted actions and from which, following a specific screenshots.json, screenshots can be taken. The process of scripting all screenshots of the official TYPO3 documentation is an ongoing process, with 366 screenshots currently transformed.

As the project is still organized centrally, extensions from which screenshots are to be taken must be registered with this project - as is already seen with the Extension Builder. This will be relaxed in the future to support any third-party extensions in taking screenshots without having to register them centrally. At the moment, this tool mainly supports the TYPO3 Documentation Team and the TYPO3 Core Team when documenting.

See also:

Migrating Documentation Rendering From Bamboo to GitHub CI

The documentation rendering was migrated from the self-hosted Bamboo server to an easier to use CI chain on GitHub allowing more team members to manage the rendering chain and optimizing the workflows.

Continuous Updates of the Official TYPO3 Documentation

Another approach to combat outdated documentation, in addition to the TYPO3 Screenshots project, is the introduction of a fast update cycle, whereby changes to the TYPO3 Core are transferred to the TYPO3 documentation on a weekly basis. This resulted, for example, in the documentation being up to date in time for the release of TYPO3 v11 LTS.

Rewriting Parts of the Official TYPO3 Documentation

The official TYPO3 documentation grows over time, so it is occasionally necessary to readjust the paths to lead the reader directly from question to answer.

The first step was to reorganize the welcome page, rewrite the introduction content and group the topics to the different TYPO3 user types (administrator, developer, consultant and editor).

The first manual any new user sees is the Getting Started Guide. It has been completely rewritten to make the first steps a user has to take as easy as possible - from installing TYPO3 to creating the first site and pages.

As the installation of TYPO3 found its new home in the Getting Started Guide, the Installation & Upgrade Guide was in turn rewritten into the Upgrade (only) Guide, for the first time directly distinguishing minor and major TYPO3 upgrades.

Unlike the third-party extensions, the system extensions were not explained by their explicit documentation, but by pieces of documentation scattered in the official manuals. To facilitate maintenance and increase usability, we have provided each system extension with basic or even full documentation, such as the Admin Panel or the Redirects extension.

Writer’s Guide

Even if the documentation team has developed a certain professional attitude towards documentation writing, most team members are developers rather than editors by profession. And even if the team establishes new writing guidelines from time to time, they are based on the developers’ perspective and there are still white spots in the guidelines. That’s why this year, an experienced team of editors at Open Strategy Partners churned out a complete Writer’s Guide that covers all aspects of writing clean technical documentation - from the spirit of the TYPO3 project and general authentic communication to specific rules, from narrative structure to terminology, from styling to accessibility and much more - and handed it over to the documentation team. In a final step, this large compendium will be merged with the existing rules and forged into the final TYPO3 Documentation Guide in 2022.

The TYPO3 Guidebook

The editorial team at Open Strategy Partners, with great support from the TYPO3 Association, has written a comprehensive beginner’s guide book to web publishing with the TYPO3 CMS, called “The TYPO3 Guidebook”. It takes a fresh perspective that is not developer-centric, but includes editor and administrator perspectives - and is written along the authoring guidelines mentioned above.

See also:

Extension Award for Documentation

Since documentation is often seen as the unwanted child next to coding and testing, we wanted to raise awareness for the topic with the first Extension Award for Documentation at the end of this year. The TYPO3 community was called upon to vote for the three best third-party extension documentations - that were already adapted to TYPO3 v11 LTS. Besides awarding the official cash prizes to the winners, we took the opportunity to give feedback to the authors of the documentations.

See also:

Contribution Acknowledgements

Like all teams, the documentation team is always trying to engage people to contribute. One difficulty seems to be that casual contributors often don’t understand how important their contributions are, and the value that even small efforts can make. We also want to make sure that the motivation of existing contributors remains high.

In June 2021, we searched GitHub to identify each and every person that had contributed to the docs in some way since October 2020. We found 16 highly active persons, 40 moderately active persons and 21 newbies. We sent an email to each of them, expressing our thankfulness and explaining how valuable their work is. Most importantly, beyond words, they were encouraged to claim 75, 50 or 25 Euros of the documentation team budget. In the end, 41 of the 77 receivers actually used the reimbursement tool and requested 2150 Euros in total.

We are under the impression that the money is appreciated, as we have seen positive responses from all over the world, and could see people appear in the typo3-documentation team Slack channel.

Guidelines

In addition to the major achievements and features added to the documentation toolset, some documentation guidelines were also created and applied throughout the official documentation that should be followed by you, the authors of the official TYPO3 documentation, and guide you, authors of third-party extension documentations.

Reduce Git Repository URLs

Reduce types of git repository URLs to

  • https://github.com/ (for browsing and reading only) and
  • git@github.com: (for working)

and remove git://github.com/.

Unify Top-Level Domain of Dummy URLs

Unify the top-level domain of dummy URLs to (by order of preference):

  1. https://example.org
  2. https://example.com
  3. https://example.net

Use subdomains if you need additional URLs. Use https://example.localhost for local domains. Do not use domain.de, domain.tld, etc. This is in accordance with RFC 2606.

See also:

Disable All Dummy URLs

Sphinx automatically converts simple URLs into links. This can be unintentional in certain contexts, for example when using dummy URLs. Disable all dummy URLs with the samp directive.

Example code and rendered documentation:

:samp:`https://example.org/typo3`

See also:

Unify Placeholder Syntax

Unify placeholder syntax: use <placeholder> as default placeholder style in URLs and code since it’s standard in Backus–Naur form. Do not use {placeholder} (which has even side effects in samp directive) or [placeholder] etc…

Example code and rendered documentation:

:samp:`https://example.org/typo3/main?token=<token-id>`

See also:

Content Elements

We are continuously expanding the set of reST content elements available to authors who follow the official path to render TYPO3 documentation.

Graph and Diagram Content Elements

The integration of Graphviz and PlantUML gives you the ability to code graphs and diagrams in your documentation using the new reST directives graphviz and uml. Instead of creating and updating both types in external tools and including them as images, you use inline notations that make searching and updating easier, which is especially useful in open source projects with many and changing contributors. Standard styles are provided for both types, ensuring a consistent look across all documentation.

See also:

Card Content Element

Over the summer, the official documentation welcome page was redesigned to provide better orientation for readers, especially newcomers. As part of this redesign, the card content element was introduced for the documentation that nicely supports grouping deep links by category. Consider using it in your extensive extension documentation as well.

See also:

Tabs Content Element

In addition to the card, another content element of the documentation was introduced that is already familiar from similar documentation: the tabs. They provide a compact way to present a topic from different perspectives, with each perspective presented in a tab. When the reader changes tabs, this change is synchronized in all tab content elements.

See also:

Configuration Values Content Element

The configuration values content element can be used to document configurations in a structured way, independent of the programming language. Values can be for example PHP arrays, TypoScript, XML and YAML.

See also:

PHP Domain Content Element

To document PHP classes and the like in a structured way, the Sphinx extension PHP domain is integrated into the rendering process.

See also:

Sidebar Content Element

To enable the reader to navigate quickly, the sidebar content element is available. It displays a box with custom content to the right of the current paragraph.

See also:

Summary and Outlook

The year 2021 was a busy year for the documentation team with many improvements in many areas and some new features. These new features will continue to be rolled out and refined in 2022. Stay tuned!

The most important thing you can take away from this article as an author of a public TYPO3 extension is to register the documentation for publication on docs.typo3.org so that it can be found via the new global search, increasing its visibility and popularity.

We wish you a good start into 2022!

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