Extension Award 2021—Announcing the Winners

Categories: Development, Community, Documentation Created by Sybille Peters
Gold bar
Photo: Jinming Pan / Unsplash.com
The TYPO3 Extension Award for Best Documentation 2021 has the following winners:
  1. news by Georg Ringer
  2. typo3_console by Helmut Hummel
  3. 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:

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.

Learn how to add diagrams to your documentation.

Another feature that was added recently, is the possibility to automate screenshot generation. Outdated screenshots can be annoying. They make the documentation look outdated and will confuse readers. Automated screenshot generation must be set up once, but will continuously and automatically ensure that screenshots are up-to-date. This is another huge step to ease maintenance for extension authors. The extension_builder was the first community extension to use this functionality.

Read an introduction to automated documentation screenshots with Puppeteer.

Learn how to automate screenshots

You can also use a card layout for the start page, as implemented in the news extension documentation and in the official TYPO3 documentation. It can be used to give small teasers of individual chapters or pages.

Adding an Edit on GitHub button is another step towards improving the documentation. It makes it easier for non-developers to contribute.

Learn how to add an “Edit on GitHub” button to your documentation

More examples of how to improve your documentation is available in the comprehensive Writing Documentation guide.

Thank You

Many people have helped make the award possible, we name a few who have put in extra effort:

  • Thomas Löffler for providing a nomination and voting mechanism on extensions.typo3.org.
  • TYPO3 Community for nominating and voting.
  • Alexander Nitsche for reviewing the documentation of all nominees, giving insights, ideas and texts.
  • Documentation Team for providing a number of features which can be used for improving extension documentation.
  • Extension authors and contributors who are continuously improving their extension documentation.
  • Design Team, Volker Neuenhaus for creating a logo and helping with the email template.
  • Felicity Brand and Mathias Bolt Lesniak for fine-tuning and polishing the news articles for typo3.org.
  • The TYPO3 Association
Additional contributors for this article
  • Proofreader : Mathias Bolt Lesniak