Sybille Peters
- news by Georg Ringer
- typo3_console by Helmut Hummel
- container by Achim Fritz and Benni Mack
We would like to congratulate the winners as well as all the extension authors who have supplied documentation and worked on improving their documentation over the last months.
The news extension evokes fond memories in Documentation Team lead Martin Bless, as it was the first extension to add reStructuredText (reST) documentation files and be rendered on docs.typo3.org, back in 2012. Today news has extensive documentation with a number of references, best practices and examples. Whenever you need the documentation, you can find helpful snippets, tips, and insights, whether it is for setting up the routing, adding a custom tabs to the link browser, or extending the extension.
The extension typo3_console provides additional commands, beyond what is offered by the TYPO3 CLI tool, that many consider essential when maintaining a site. The command reference is automatically generated, which guarantees consistency and helps ensure that the information is up-to-date. The documentation is well-maintained and can be used as a handy reference with more information than what is displayed in the CLI help texts. We are pleased that more of this functionality is being migrated to the TYPO3 Core and look forward to more code and documentation keeping this high level of quality.
The container extension is one of several extensions to provide containers for creating nested (“structured”) content elements. Though a more recent addition, it has quickly gained popularity. The documentation uses an “all-on-one-page” concept using a single README.md. This is sometimes preferred for documentation which is not very extensive. One advantage is that the content is easily accessible on one page and fully rendered on GitHub and Packagist. It contains all necessary information, is concise and well maintained. It includes information about why the extension was created and how it compares to the other extensions and necessary steps to set it up. The content is well structured, formatting is used to improve readability.
All winning extensions provide functionality and documentation that is considered very useful by the community.
Also worth mentioning are some extensions that have been nominated and where dedication to documentation is especially visible:
- schema and matomo_widgets by Chris Müller
- mask by Nikita Hovratov (originally created by Gernot Ploiner)
- external_import by François Suter
If you are wondering how many votes a particular extension documentation received, please have a look at the full list of voting results.
Benefits of Writing Documentation
Similar to tests, documentation has a self-healing effect for the developer, who gets the opportunity to reflect on their own implementation when explaining it and validating decisions made. A second benefit is the increased visibility that comes from giving decision makers insight into the extension without having to install and try it out. Furthermore, a documented extension has increased visibility: It can be found via docs.typo3.org’s new global search, which searches all official documentation manuals, as well as extension documentation.
Writing the documentation in reST markup and compiling it with the official TYPO3 Sphinx template provides you with a defined set of well-designed structural elements that improves the clarity and readability of your documentation.
Documentation Feature Highlights
Lately, many new documentation features have been added for documentation rendering on docs.typo3.org. One example is the PlantUML diagram, that can be used to visualize abstract topics, such as event handling and domain modeling, as seen in the well-written schema extension’s documentation.
