Write-the-docs camp


In the spirit of Write-the-docs a documentation camp was held in the Grenoble area from the 2 to 5 May. The camp lasted 3 days and was dedicated to working on reviewing the new documentation (http://tango-controls.readthedocs.io/en/latest/) and  identifying and writing missing documentation for Tango.

The meeting is sponsored by the Tango Controls Collaboration. Travel and accommodation were paid for by the Collaboration. The following people participated: Piotr Goryl (3-Controls), Olga Merkulova (IK), Lukasz Zytniak (MAXIV), Lukasz Dudek (Solaris), Matteo di Carlo (INAF), Matteo Canzari (INAF),  Igor Khokhrakiov (HZG), Reynald Bourtembourg (ESRF), Jean-Michel Chaize (ESRF), Stuart James (ESRF) and Andy Götz (ESRF).

The meeting took place in Grenoble and in St Nizier du Moucherotte (a village at 1200 meters in the Vercors mountains) in the house in the middle of this picture below. The bad weather (rain and snow) enabled the team to concentrate on their work writing documentation and cooking!

Write-the-docs house in St Nizier du Moucherotte

A real team spirit was created and each person had a role to play. From the absolute beginner (Stuart) to the experienced kernel developers (Reynald and Igor) the other roles covered were web designers (Olga and Jean Michel), chief sphinx documentation master and guru (Piotr), chief sphinx converter (Lukasz1), device server model and hdb++ specialist (Matteo1), high availability (Matteo2), chief git+travis master (Lukasz2), mtango+kernel (Igor), layer model specialist (Stuart) and last but not least organiser and chief cook (Andy). The picture below gives you an idea of how concentrated the team was at work.

Write-the-docs team at work

The outcome of the Write-the-doc camp exceeded expectations. The meeting built on the existing documentation by Emmanuel, Pascal, Gwenaelle, Nicolas, Faranguiss, Jean-Luc, Igor, and many others, the excellent documentation tool Sphinx by Georg Brandl presented and adopted at the last Tango meeting, the analysis by Lize presented at the last Tango meeting, and finally the mindmap by Olga. The results will be presented at the next Tango meeting in Florence (see slides from presentation by Piotr)

In the meantime here is a brief summary of the achievements - the documentation has been re-organized to be a coherent whole, almost all existing docs have been converted to sphinx, new diagrams have been produced and integrated. Some old ones have been updated. New Getting started's have been started. In brief the Tango documentation now has a single place where it is maintained and can be extended. It is much more coherent for beginners, intermediate and experienced users to find. It is built automatically. It is easy to contribute to - all you need is a text editor and an account on GitHub. A virtual machine is available with all the tools (Sphinx, pandoc, git, pycharm) pre-installed.

The Write-the-docs team had a great time getting to know each other, tasting local French specialities and Italian cooking. We all learned a lot and found that writing documentation can be as fun as writing code! We decided at the end that the camp should be repeated on an annual basis.

As the saying goes "the proof is in the pudding" the best is to check it out for yourself. The result can be viewed here - http://tango-controls.readthedocs.io/en/latest/

The pictures above are courtesy of Olga Merkulov. More pictures of the event can be found at Lukasz Zytniak picture gallery.

Back to news list