Documentation Team code sprint, April 2014
April 16, 2014
From April 10 to April 12, the Documentation Team held its first ever code sprint in Fribourg, Switzerland.
We started with an afternoon of discussion, aimed at taking stock of our current situation. Most participants had prepared an overview of their area of responsibility and presented its current status. We then moved to shaping how we wanted this situation to evolve, what could be cleaned up, consolidated, improved, etc..
A crucial topic was the Flow application meant to be the central hub for documentation rendering and which has yet to be used on the production server. Having around the table all people involved - at some level or other - in documentation rendering was the ideal opportunity to share knowledge and optimise the various pieces of software as well as the connection between them. In particular, we have been taking a first look at RabbitMQ, which the typo3.org/TER team aims to use for sending out messages when a new extension is uploaded to the TER. It is not only a process into which we need to hook, but also one which could be used internally in the longer term.
Beyond a better understanding of the current situation, we could improve the structure of the Flow application and improve the status of the Chef recipe used to build docs.typo3.org. This is an important step, as this Chef recipe also makes it possible to deliver a Vagrant box, providing each developer with a fully working, local copy of the documentation server. This will greatly simplify our development work. The Vagrant is not yet fully ready.
Much discussion occurred also around the problem of templating. There is a drive to change the design of docs.typo3.org, to make it more sexy and accessible, in particular to beginners. Such a change implies regenerating all the manuals, since what we currently deliver are fully rendered HTML pages. Making the templating more flexible is thus a very important topic. A first step in that direction was to test usage of Twitter Bootstrap to base our templates on a commonly used HTML/CSS framework. The first try was promising. The next steps are to review the user experience on docs.typo3.org and start thinking about the new design.
Special guest Dominique Feyer investigated the possibility to integrate documentation into a TYPO3 Neos web site by importing JSON generated with Sphinx. After two days he had a very interesting proof of concept. Moving the whole site to Neos is not strictly on the agenda, but this successful test makes it a serious path to explore for the future.
We also welcomed Guido Haase, already a member of the Editorial Team. He took this opportunity to discover the Documentation Team, its tools and processes, with the idea of joining our efforts in the future. Guido started working on updating the Getting Started tutorial.
We are delighted of our first code sprint. It was a great experience and we really made progress on some long-standing projects. If you are interested in following our progress more regularly, consider subscribing to the documentation mailing list.
All of this would not have been possible without sponsoring. First and foremost, we had a budget thanks to the TYPO3 Association, which covered the travel and accommodation for each participant, as well as other small expenses.
Hemmer.ch SA provided us with a very nice and cosy meeting place, at no cost, with tee, coffee and performant network connections.
We had a very nice social event with a guided tour of the H. R. Giger (of Alien fame) Museum in Gruyères, Switzerland, followed by a delicious cheese fondue. This was sponsored by Cobweb Development Sàrl.
I would also like to thank all companies who made their employees available: Martin Bless (Martin Bless Freelancer), Karsten Dambekalns (TechDivision GmbH), Dominique Feyer (ttree Sàrl), Guido Haase (Ingenieurbüro Haase), François Suter (Cobweb Development Sàrl), Fabien Udriot (Ecodev Sàrl) and Xavier Perseguers (causal; Sàrl).
Many thanks for making a great sprint even better!