Reimagining the TYPO3 Documentation

 

 

In the last few years TYPO3’s documentation has grown steadily, thanks to the Documentation Team and many contributions from the broader TYPO3 community. Unfortunately, the docs have grown without an overarching structure or content strategy. Now we find ourselves with a lot of useful documentation that can be hard to find or that is not always grouped logically.

We regularly receive feedback that TYPO3 newcomers, who are unfamiliar with the CMS, have difficulty finding the information they need to get up and running with TYPO3.

Recently, the Docs Team asked ourselves the question: 

“What would the documentation look like if we started again from scratch?”

A healthy and robust discussion ensued and while we might have different ideas about how to approach this challenge, we all agree that understanding our readers and meeting their needs is what will drive a lot of decisions.

Catering For New Users

Introducing Terminology

To make things as easy as possible for new users, we need to change some of the language we use when introducing TYPO3-specific terminology to newcomers. People who are just getting started with TYPO3 don’t know what a site package is, what Fluid is used for or why they should care about TypoScript. These are terms used exclusively in the TYPO3 universe, and can be a barrier to entry.

Improving the Content Structure

We will restructure the main documentation to better match a new users’ journey through TYPO3: from installing, configuring and creating their first templates to extending the system itself. 

The main hierarchy we are currently planning is oriented around goals and topics instead of specific user groups (“integrators” vs. “administrators”) or internal structures that new users won’t be familiar with. A user who wants to find out how they can preview scheduled content, for example, wouldn’t necessarily know to look in the Admin Panel documentation.

Empowering Experienced Users

Experienced users usually have some idea what they are looking for, but might need assistance finding it. These users are more likely to rely on search than the navigation hierarchy. The TYPO3 Documentation Search Initiative, (#t3docs-sig-search channel in Slack) led by Tymoteusz Motylewski, is currently working on adding a global search with tagging and filtering capabilities. Stay tuned for news about this exciting development soon. 

Get Involved

This article is just a quick glimpse into our current work. If you want to give feedback or get involved you are welcome to join us in in #typo3-documentation channel in Slack. We meet bi-weekly on Fridays at 10:30 AM CEST (06:30 PM AEST, 09:30 BST), the meetings are announced in the channel. We would be happy to have you!

More About the Documentation Team