Documenting TYPO3 Version 12

Categories: Community, TYPO3 CMS, Documentation Created by Lina Wolf
When integrators and editors start using any version of TYPO3, they need to be able to access documentation relevant to the version they are using. We believe that accurate, up-to-date documentation should be available at the start of the lifetime of an LTS version. That’s why we’re taking steps now to get ready for TYPO3 version 12 LTS.

Extension Authors Need Good Docs Too

It’s not sure integrators and editors that rely on up-to-date documentation. Extension authors need to know about any Core API changes so they can update their extensions accordingly. 

We want to help remove one of the major blockers for upgrading: extensions that are not yet updated. We want to enable extension owners to update their extensions early. They should start working on their code with the release of TYPO3 v12, and have it ready for production by the release of the LTS v12. For this, extension authors rely on the Documentation Team to produce readable documentation with useful live examples.

How We Approach Documenting a New Release

Every change made in the TYPO3 Core has a corresponding Forge ticket and at least one Changelog entry. To get a better overview of each ticket involved in a release, and the corresponding documentation required, we are experimenting with a new GitHub Project: Changelog-To-Doc. Every Changelog entry automatically creates a GitHub issue in the project. 

We can categorize these issues to give an indication of the effort and action required. 

No Docs Required

Some changes need no documentation beyond the entry in the Changelog. For example,

  • If a hook or API method has been removed that was never documented in the References orTutorials in the first place.
  • If a Feature includes changes to the GUI that does not need to be documented. 

Action: We can just close these issues.

Core Docs

Some changes need to be documented within the TYPO3 Core mono-repository. This includes:

  • Changes to system extensions that have their own manual (for example, form, adminpanel, impexp, etc).
  • Documentation that is automatically generated from source code (for example, Fluid ViewHelper Reference, the API of a new Event).

Action: We can link the Forge ticket to these issues.

Expertise Required Docs

Some changes impact documentation that falls in a particular field of expertise, or an area of functionality. 

Action: We can tag these issues, then group them and work on documenting them as a batch. 

How You Can Help

Come join the Documentation Team! We are much more fun than our name might suggest! You do not need to be an expert to help us. 

We need people to help tag issues, and follow up to remind those who worked on a ticket when there has been no action.

We need help with reviews of the English language (hard to learn), and ReST syntax and semantics (easy to learn).

You can help us by reviewing anything from no-brainer pull requests to trickier PRs where you need to keep trying to find someone who has knowledge on a new topic.

You can help us by applying best practice throughout the documentation; and by trying to find out what is best practice.

To whet your appetite, here is a sample of open questions in the Documentation Team:

  • How do we hint at dependency injection in small code snippets of a few lines, without any class context?
  • How can we convince people to use sitepackages and not store their Fluid template in the fileadmin, and the TypoScript in the database?
  • Should extension developers use Extbase; and how to properly develop an extension without Extbase?

You can make a real difference here! Come along to one of our meetings held on the third Friday of every month, or add your voice to the conversation in the #typo3-documentation Slack channel.

Additional contributors for this article
  • Copy Editor : Felicity Brand
  • Content Publisher : Mathias Bolt Lesniak