TYPO3 Documentation Team Report 2021

 

 

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.