The Documentation Team in early 2013
June 18, 2013
Author: François Suter
The first six (nearly) months of 2013 have been a very busy time for the Documentation Team. The ReStructured Text project in particular has made very good progress.
Usage of ReStructured Text (ReST) for the TYPO3 documentation has been the focus of the Documentation Team's activity since last year. The biggest achievement was already announced in February: TYPO3 CMS, TYPO3 Flow and TYPO3 Neos all use ReST for their documentation and are now all housed on docs.typo3.org. This was a major incentive of the ReST project and it has been a reality for a few months already.
A lot of effort was also put into updating the official manuals. ReST has made our life definitely easier in that area. In particular we can finally cross-link between manuals with unprecedented ease and there is no doubt that having more links improves the user experience. All reference manuals (TypoScript, TSconfig, TCA, plus TypoScript Syntax) were brought up to date with TYPO3 CMS 6.1. A huge amount of work was put into updating Core APIs, which was stuck back at version 4.3. The next candidates for a big refresh are the Getting Started Tutorial and the Installation and Upgrade Guide (along with the Editors Tutorial, as there are some redundancies across these manuals).
Manual versions are now managed on docs.typo3.org. A popup menu makes it possible to switch between available versions. Furthermore we also have a "latest" version which corresponds to the current development version of the TYPO3 CMS Core. Some new features of TYPO3 CMS 6.2 are already documented today!
In the meantime the wiki was also maintained. It went through a number of upgrades and now uses MediaWiki 1.21. That way it also benefits from the newest usability improvements in the MediaWiki software.
Back to ReST we have two big objectives on our radar:
- properly handle extension manuals (recognise ReST-based manual automatically, include proper navigation and styling in the rendering, provide links for the TER)
- switch all the manuals of the TYPO3 CMS Core to ReST (currently ongoing at https://github.com/fsuter/TYPO3.CMS.Documentation.Migration).
There will be three documentation-related workshops at T3DD13:
- Martin Bless will hold an introduction workshop: at every full hour you can get an introduction to ReST, then you can stay as long as you wish, work on some ReST stuff and get support.
- Philipp Gampe will lead a workshop aiming at improving the Editors Guide and in particular avoid the redundancies with the Getting Started Tutorial.
- as for myself, together with Xavier Perseguers, I propose a workshop for developing an extension to integrated ReST-based documentation in the TYPO3 CMS backend.
We hope many of the participants will be interested in joining us. If you are not attending T3DD13 we still hope that you may be interested in joining the efforts that will be started there. I think we have achieved a lot, but we are really only a few people and could use having more active contributors. Hopefully the simplicity of using ReST will attract more people to documentation.
If this motivates you to help, get in touch!