Tag Archives: sysadmin guide

Documentation in GNOME 3.12

Wave breaker at SheringhamThe documentation team have worked long and hard to make 3.12 one of the best documented releases in recent history. Thanks to our translation teams, it is also one of the best translated in many years.

The team especially appreciated the detailed bug reports about changes to the UI and functionality in some applications (thank you Debarshi and Christian, please keep them coming), and lots of proof reading by translators.

There has now been one full release since the translation/documentation BoF at GUADEC 2013 where we discussed implementing documentation freezes toward the end of the release cycle. As with many things, changes to UIs and functionality tend to happen closer to the deadlines rather than early on. With many changes happening in the Shell and applications over the last few years, this has lead to unstable documentation that has needed regular updates or rewrites. The instability creates a high workload on the team during the last few weeks leading up to the release. To complicate the issue more, both documentation and translation work often starts at the same time: after the UI freeze. Unfortunately, it also means that it is not practical for the documentation strings to be frozen as we do not have the resources to finish updates early. At the BoF, we came up with a work around: whenever the help was finished for a module, the documentation team would email the translation teams to let them know. We have now done this for one full release and the feedback has been very positive. Alternatively, the help statuses can be tracked on a wiki page, but the update notification emails are not pretty.

Another status tracking issue that we came across this cycle is that there is no easy way to view images and screenshots across all modules. I have gotten in touch with the damned-lies maintainers who have volunteered to see if they can adapt some of the webapp to work for the documentation team.

For the 3.14 release, the documentation team will focus on the system administration guide, alongside the usual user and developer documentation updates. Developer documentation will be reviewed at the upcoming Developer Experience hackfest and we are hoping to have a team meetup at Open Help!