Guide to TYPO3 Documentation – Part 1: The User-Interface

The documentation of TYPO3 has a quite bad reputation, but that is not valid. Thanks to Martin Bless, it has evolved much in the last few years. In this and and some following posts, I will introduce you to the current state and structure of TYPO3 documentation and the various sources. 

This post is about the user interface of docs.typo3.org and its hidden gems.

In the last years Martin Bless (@marantern) invested much time and dedication into the infrastructure of TYPO3 documentation. The result is the domain “https://docs.typo3.org“. It is the one stop shop for TYPO3 documentation, the central place where all docs in rst and sxw format are rendered to HTML and quickly available to your fingertips.

TYPO3 Documentation – Main Project

As on most website, the logo and the claim is the link to the home page of the website. No matter where you are … this link brings you back to the main page https://docs.typo3.org.

TYPO3 Documentation Subproject

Right below is the link to the start page of the subproject. A subproject can be a reference, like for TypoScript or the TCA or some guide or other tutorial. That should be enough for now. In the second part of this series, I will go into the details of the content structure.  A concrete example: If you are using the TypoScript documentation and “got lost” in a subpage , this link will bring you back to the start page of TypoScript documentation.

 

Search

Below these two main links, there is a search field.

A search triggered in this field triggers a search in the current subproject … but not in all documents of the domain “docs.typo3.org”. That means, if you are in the TypoScript documentation, it will only search and find result within the TypoScript part, but not in any other official parts of the TYPO3 documentation. In case you want to search the complete site, it is better to use a search engine like Google and limit the search to the site “docs.typo3.org”. At Google the scope of the search can be limited with the “site:” tag to a certain website:

site:docs.typo3.org my-search-term-1 my-search-term-2

Subproject Menu

In the black area are the chapters (aka menu) of the current subproject. The plus sign in front of a menu entry indicates that it has a submenu. A click on the plus sign shows the titles of the chapters below.

Version Switch

A really neat feature is the version switch at the bottom of the menu column. Between each version of TYPO3 there are more or less changes in TypoScript or the API. If you are on a reference or a guide, you can easily switch between the different TYPO3 versions.

On the last line of the menu column there is the current version number printed. If you click on it, a submenu is opened, where you can switch between the different available TYPO3 versions. So if you do not find a specific option or if there is something, that does not work with your current TYPO3 version, you should check, whether you are on the right version of documentation.

“Edit me on Github”

Most of you will have notices that there is a “Edit me on Github” button in the upper right corner.

The goal of this is to lower the barriers to contribute to TYPO3 documentation. I will describe the details and bells and whistles, how to contribute in the third episode of this series.

“View page source”

As ReST format has the reputation to be hard to learn, you will probably see the one or the formatting, where you think “How did the author do that?!”

And here is the rescue: At the very bottom of each official page, there is a link “View page source” which will open the original rst file of the TYPO3 documentation. There you can spy for how the author achieved it.

Conclusion

This was the first part of the “TYPO3 Documentation Series“. I covered the user interface based on Sphinx.

The second part will be about the contents of the official TYPO3 documentation and how they are grouped on the website.

Contributing to TYPO3 documentation will be the third part of this series. In this episode I will dive into the details, how to write documentation and how to get it online.

Credits
I found the blog post image on pixabay. It was published by Steve Buissinne under the CC0 public domain license. It was modified by myself using pablo on buffer.

1 Comments

Leave a Comment.