Running a Docs Workshop at DevConf

With Bara Ancincova of Red Hat docs fame, we ran a docs workshop at this year’s DevConf in Brno. It was mostly a follow-up to to a Fedora documentation hackfest held at Flock 2014 in Prague. Quite a few people showed up Saturday afternoon, which was a nice surprise, given that docs sessions are usually not among the most attended at a technical conference.

Some of the topics we touched included:

• DevAssistant. Slavek Kabrda joined us to give a short presentation about what DevAssistant has to offer when it comes to kick-starting your projects. Based on the ideas we first explored at Flock, Slavek and Jaromir Hradilek started to hack on a new assistant that will mostly serve people who are getting started with DocBook, the Publican toolchain, and Fedora documentation. However, there is nothing preventing us from making a step further and including support for other documentation projects, formats, and toolchains, if there is interest (and people willing to help out).
• The plan is for DevAssistant  to be able to create a complete writing environment that would let you set up a basic structure for your new documentation project, with templates and different content types.
• DevAssistant works well in both CLI and GUI mode. While developers and some documentation writers might prefer to work on the command line, newcomers often prefer a GUI option. Both options, however, provide an integrated solution that lets you work within a single app (and write in a text editor of choice). This means that DevAssistant aims for both the developer and documentation writer audiences, which often overlap anyway.
• Building documentation. We talked about Jenkins, which is typically used in a software development environment.  Since Jenkins can run pretty much any commands available on the server, it can also easily be used to take care of your continuous documentation builds. This makes docs QA’ing and reviewing so much easier.
• Pavel Tisnovsky is working on Jenkinscat, a dashboard for Jenkins to let you easily manage documentation builds.
• Publishing documentation. This is a long-standing issue in Fedora. We explored the idea of using Jenkins and Jenkiscat for Fedora.
• Testing your documentation. In this segment, Jaromir Hradilek talked about Emender, an emerging test automation framework for documentation. Its goal is to allow you to run a number of tests against your (semantic) documentation. Ultimately, this can save tons of time on the docs QA front, especially when you are maintaining a huge and ever-increasing number of documents for different projects or products.

A number of great ideas were put forth for future documentation events which I hope we could organize later this year.