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.

Fedora Docs FAD 2014

The Fedora Docs team recently organized a FAD (Fedora Activity Day), with the goal to work on areas such as attracting new contributors, mentoring, providing HOWTOs for writers, and preparing the project’s infrastructure to migrate from the old Publican 2-based publishing system to Publican 4 and Koji.

The FAD had two meeting locations, one at Red Hat’s office in Raleigh, NC, and the other one at Red Hat’s office in Brno, Czech Republic. We set up a teleconference call that also allowed remote people to participate.

Other docs team members have already blogged about the progress we made over the course of three days. There is still a lot do, and you are welcome to join the fun.

At the FAD, I also published a new revision of the Fedora Software Collections Guide, which serves as the official manual for people getting started with Software Collections (SCL) packaging. The guide can be useful not only for Fedora packagers, but also for people packaging for EPEL 5, 6, and 7. The SCL packaging guidelines are currently being approved by the FPC and Marcela drafted a proposal to include the first SCL (ruby193) in Fedora 21. Even though SCLs are not yet officially supported in Fedora, you can already get the ruby193 SCL from the Copr build system.

Thanks to all the FAD attendees, and to Red Hat for taking care of us throughout the event, for providing the meeting space and great catering!

For Czech speakers, I also put together a short report which you can read on