This Week in TYPO3 (2016, Week 6)
A special on TYPO3 documentation infrastructure, certification, T3Rookies Summer Camp 2016, TYPO3 usergroup India and bootup-camps gaining popularity! All things TYPO3 community!
How Documentation Professionalises TYPO3
The TYPO3 project was always amazing. But especially with all the changes started in 2015 we see more retention. There is a lot of regained adoption, but still RTFS (Read The Fucking Source) is a barrier for adoption. Good documentation creates traction for a project. Professionalism of a project comes with documentation. Documentation underlines the value developers rate their project with.
Especially with the steep learning curve people mention as a hurdle to adopt TYPO3 steps to set up and deploy TYPO3 are important. I do consultancy for many different open source projects, these days with Age of Peers, and in the majority of projects documentation, whether user oriented or technical plays a large role in community health.
Project documentation:
- describes the project and issues it is trying to solve
- helps people getting started
- solves problems
- helps developer(s) validate that what they write makes sense
- supports maintenance and actively stewards community maintenance
- plenty more…
I talked to Martin Bless who is working on the infrastructure for documentation for years already. Martin points out that docs.typo3.org is still not well-known enough to people. He is “fiercely determined” to continue with this — more than ever. ‘Nowadays open source projects either have sufficient documentation or die in the end.’ Martin mentions. TYPO3 will not go lost in history because of lack of documentation. At least that is his personal mission.
Martin says:
I’m very happy I could make the new theme (for docs.typo3.org) reality this year and that I pushed that through. People like it a lot. It really makes a difference. Soon we will switch the extensions to the new theme too. Xavier Perseguers has gone far on that track already. Each extension author then should add one file ‘Settings.cfg’ with a bit of meta data (title, author, copyright, description). So that’s where people should jump in. Besides that, it has never been easier to contribute to documentation (press the “Edit me on Github” button). Everybody should start doing that. Many already do, which is great.
Next step I’ll do is: pick an 7.6 LTS Introduction package, change layout and styling a bit and make that the start page on documentation. Then we can have that “more sexy” and add all the news and pointers to how-to’s there.
There is another thing in the pipeline. Looking at this page: https://docs.typo3.org/typo3cms/FileAbstractionLayerReference/Developers/Api/AllTheLinks/Index.html#file you can see the start to document the FAL API (File Abstraction Layer – Application Programming Interface). You will notice that linking to the API is doable already. In the API you can find what the Core developer wrote as PHPDOC comment IN THE CODE:
There now is a way to automatically insert those Comments=Descriptions of the Core developer into the documentation page. That really makes a difference! Core developers wouldn’t have to change much for this — just write complete sentences. And there is more to come