So I’m here in Karlsruhe, Germany attending GUADEC 2016. Today was the second conference day with the GNOME Foundation AGM, which, as the tradition goes, included team reports. As for L10n & docs teams, the update from the GNOME Translation Project was given by Alexandre Franke and the docs update was given by yours truly.

20160813_172452If you are at GUADEC tomorrow, don’t miss Kat’s talk Documentation: state of the union with more detailed updates on what’s been happening in GNOME docs land over the past 12 months.

20160813_172544Starting Monday, we are having a GNOME docs sprint at the GUADEC BoF venue. Our primary goal is to work on GNOME Help updates for the upcoming stable release but come join us even if you are not a contributing writer yet. We will guide you through the writing process and gladly convert you into a successful GNOME writer!

badge-goingtoLast but not least, big thanks to the GNOME Foundation for sponsoring me!


Converting DocBook into AsciiDoc

For quite some time, lightweight documentation formats have been a big thing in the world of open source community documentation. While corporate environments are not very eager to move from their (often) ancient documentation platforms due to cost concerns, it is usually less of an issue for a typical open source documentation project out there to migrate to a new format.

I’ve recently started converting one of the open source documentation suites that I contribute to from a Publican-based DocBook XML source into AsciiDoc, which has been getting lots of attention especially from developer-centric communities.

The semantics of AsciiDoc is based on DocBook and AsciiDoc draws its roots from this industry-standard XML language. This allows for an easy AsciiDoc to DocBook conversion. Sadly, when you need to convert your DocBook content into AsciiDoc, you are left with a number of conversion tools which are either unmaintained or have incomplete support for DocBook syntax. This is an important aspect to consider when you are planning to migrate your documentation to the new format, especially if your documentation suite is rather complex and features a rich set of syntax and semantics.

Preparing your XML document for conversion

From the tools available for the conversion task (pandoc +, docbook2asciidoc, and others),  docbookrx seems to have the most complete support for DocBook syntax. It can preserve tables, included files and images, procedures, and so on. Not all DocBook elements are supported, though. Here is an (incomplete) list of elements I had to replace with sed:

  • productname
  • menuchoice → menu:examplemenu[examplesubmenu > examplesubsubmenu]
  • guimenu → [label]#example#
  • guisubmenu → [label]#example#
  • guimenuitem → [label]#example#
  • userinput → [userinput]#example#
  • option → `example`
  • systemitem → `example`
  • remark
  • revhistory

It is always a good idea to use a version control system to track any replacements in your XML source files.

What is nice about docbookrx is that it prints a warning when it runs into an element that it can’t recognize. Some of the other converters just silently drop the unrecognised element, including the content inside it, which is something to bear in mind.

Using docbookrx.rb

  1. Clone the docbookrx repo:
    git clone
  2. Copy the docbookrx.rb Ruby gem from the repo to the directory containing the XML files you want to convert.
  3. Load the gem, specifying a root file of your document as the input file:
    ruby docbookrx.rb Admin_Guide.xml > Admin_Guide.adoc

    The gem will follow included files referenced from the root file and convert the whole document.

  4. Run asciidoctor to generate an HTML preview:
    asciidoctor Admin_Guide.adoc

Some additional clean-up of your document is usually needed afterwards but the document’s overall structure and syntax should be preserved.

Open Help Conference 2015 Hackfest Wrap Up Notes

Wrap up notes for the Open Help Conference 2015 GNOME Documentation Hackfest, Cincinnati, OH, September 28 – 30, 2015.

The hackfest was held at a lovely co-working place called Platform 53 in Covington, Kentucky, just across the river from downtown Cincinnati. During the three intensive days full of writing, the docs team managed to update tons of pages throughout GNOME Help.

  • Due to the timing of the 3.18.0 stable release, the updates, together with some updated translations, eventually landed in 3.18.1.
  • I mostly focused on updating user account, power, and printing help. These should be in a good shape now. There are exceptions, though, like documentation on enterprise login, which is pending some code-related updates.
  • Some of us struggled with getting a 3.18.0 up and running. We tried different build images from GNOME Continuous, Fedora, and openSUSE. While there seems to be a plenty of options at first glance, when it comes to being able to try out and preview the actual GNOME Desktop, I think there is still a long way to go.
  • Testing some of the cool features in 3.18 can get challenging, for example, automatic screen brightness that requires an integrated light sensor. I wish I had one!
  • I managed to get the Getting Started module in sync with most of the updates that landed in GNOME Help. Meanwhile, Jakub has been working on a different approach to Getting Started animations.
  • The team had a profound discussion about restructuring some of the most visible topics and topic groups in GNOME Help. We made good progress, although some of the issues, including content duplicity, remain unresolved. Material for the next hackfest?
  • Shaun organized a team building event for us, we watched a baseball game at Great American Ball Park. Cincinnati  Reds!

Big thanks to Shaun & Kat for organizing the hackfest, and the GNOME Foundation for sponsoring me!

View from Platform 53 towards Downtown Cincinnati.
View from Platform 53 towards Downtown Cincinnati.
The ball game in Cincinnati.
The baseball game in Cincinnati.


Notes from L10n-i18n-Docs BoF

Although this somewhat slipped through the cracks, it’s never too late to socialize the notes taken by Nuritzi Sanchez of Endless Mobile fame during the L10n-i18n-Docs BoF we ran at GUADEC 2015 (many thanks for taking them!).

The notes for the GTP (translation) part are here:

And the documentation part notes are here:

In a nutshell, the BoF attendees, both translators and documentation writers, touched a number topics spanning from screenshot automation (a follow-up from previous year’s BoF) to onboarding, mentoring and improving the projects’ getting started material for contributors, to glossaries, style guides and similar resources.

If you are interested in any of those topics, please have a look.

Hope the notes can be reused as follow-ups in future i18n and/or docs meetings.

Open Help Conference 2015

I’m here again in Cincinnati, OH for the 2015 Open Help Conference and GNOME Docs hackfest. The venue for this year’s conference is at the beautiful Mercantile Library in downtown Cincinnati.

20150926_09091820150926_095604The area around Cincinnati has a strong German heritage, so no wonder the library also features some German manuscripts. Reminds me of my years spent studying paleography.

20150926_12185120150926_095630The Open Help Conference is not like one of those industry conferences with large numbers of participants but the attendees here are, on the other hand, very focused on the specific topic of open source documentation and docs community management. It’s always cool to see how other communities approach community docs, and learn some new tricks along the way.

20150926_12195420150926_121324Great to see old faces again, and meet new ones. I’d like to thank the GNOME Foundation for making it possible for me to attend the conference and hackfest.


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.

2015 Winter Docs Hackfest

I’m here in lovely Cambridge for the winter GNOME docs hackfest. This time, the docs team is sharing a room with the Developer Experience (DX) hackfest, which provides us with a great opportunity to reach out to GNOME developers for expert’s advice.

Yesterday, Christian Hergert presented a new GNOME IDE in development, called Builder:

Builder comes with a feature-rich text editor that can also be useful for documentation writers who often author documents in XML.

Cosimo Cecchi showed us some of the downstream changes the Endless team made to gnome-user-docs and gnome-getting-started-docs. For me, personally, the most interesting part was their feedback on the GNOME docs style and content. Endless seem to target their product to a slightly different customer, still, they appear to have data on their users that the upstream project lacks. The GNOME help suite, written by different authors and in different style over the course of many years, is actually targeted at multiple audiences, spanning from quite inexperienced desktop end-users to skilled users who need to troubleshoot VMs in GNOME Boxes.

Shaun McCance showcased some of the cool features of Ducktype, a new lightweight syntax for Mallard. Although still a work in progress, this new syntax brings to the world of Mallard docs the flexibility of formats such as AsciiDoc or Markdown, which are now gaining strong popularity in both the developer and technical communication communities.

The docs team focused on squashing the bugs filed against GNOME Help and application help, and on content improvements in different areas of the desktop documentation stack. Jim Campbell worked on changing the structure and layout of Files help. He also worked with Jana Svarova on VPN docs for the GNOME sysadmin guide. Jana went through the docs feedback ML archives, responding to user comments and filing new bugs. Kat worked on application help with Jim and fixed a couple of bugs in gnome-user-docs. I worked on triaging docs bugs, and then on reviewing and updating some parts of GNOME Help and the sysadmin guide.

I would like to thank Collabora for providing the venue and catering, Kat and Philip Withnall for running the hackfests, and the GNOME Foundation for sponsoring me.

It’s been great to see old and new faces from the community, now off to Brussels for FOSDEM, then back to Brno for DevConf!


L10n & Docs at GUADEC 2014

At this year’s GUADEC, there will be a number of sessions relevant to people interested in GNOME localization and documentation:

  • On Monday, Kat will give an update from the docs team called Documentation: state of the union. Her talk will detail what has happened in the documentation realm since GUADEC 2013, so be sure to attend.
  • Team Reports on Saturday will include localization and documentation.
  • There will be a screenshot automation BoF on July 30th. Vadim Rutkovsky from Red Hat’s Desktop QE has some sweet surprise for you, translators!
  • Finally, on July 30th and 3Ist, Daiki Ueno and Alexandre Franke are planning to organize an i18n hackfest to work on translation tools, spellcheckers, dictionaries, input methods, and related fields.

I’ll be arriving tomorrow evening with Christian Schaller and other desktop people from Red Hat Czech and leaving on the 31st – hope to see you all in Strasbourg!

sponsored-badge-shadow guadec-2014-badge-large


Open Help Conference 2014

This is a belated post on the Open Help Conference in Cincinnati, OH that I had the chance (thanks for sponsoring me, Red Hat!) to attend this year. It took place from June 14-15 at a nice venue provided by Garfield Suites Hotel. The Conference was followed by the GNOME Docs Sprint from June 16-18.

The Open Help Conference is much smaller in attendance than some of the large industry conferences for technical writers out there. This actually allows the attendees to actively participate in many talks and discussions, similarly to what you can usually experience at unconferences. It was the Conference’s primary focus on docs communities that made attending each of the sessions very relevant to those of us who work on open source documentation.

Along with people representing other open source companies and communities (this included Eric Shepherd from Mozilla or Michael Downey from OpenMRS), there were also two fellow Red Hatters attending (Rich Bowen and David King). We had quite a few people from GNOME Docs, too. The Conference was organized by Shaun McCance who did a fantastic job running the whole event as he found time not only to take care of the venue and catering, but also of the social events on both conference days that took place in his lovely hometown of Cincinnati. Thanks again, Shaun!

You can check #openhelp and Michael Downey’s excellent notes to learn more about the different talks and sessions held at OH.

Open Help Conference 2014 Hackfest

The Open Help Conference 2014 Hackfest followed an unwritten tradition in the GNOME Documentation Project of having two GNOME docs hackfests or sprints annually. Unlike the sprint held earlier this year in Norwich, UK where the team worked mostly on updating the user help for the upcoming GNOME 3.12 release, the Cincinnati hackfest focused on finishing the GNOME System Administration Guide. We managed to completely rework the overall structure of the guide and redesigned the index page for the guide, following the earlier design mockups prepared for GNOME Help by Allan Day.

The restructured System Administration Guide now features the following main groups of topics:

  • User Settings (Lockdown, Pre-seed user defaults, Pre-seed email/calendar/groupware, Appearance, Setup)
  • Login Settings (Appearance, Session, Management)
  • Network (NetworkManager, etc.)
  • Software (Apps, Extensions, Management)
  • Troubleshooting / diagnosis

More details can be found on the Guide planning page.

Other things that caught my attention during the conference:

Duck Pages

Shaun’s plans for the future include an additional input format for Mallard-based documentation – so called Duck pages. A Duck page is essentially a plain text format based on Mallard XML that doesn’t use the often distracting XML syntax. Duck pages should make it easy to author single-sourced topic-based documentation with a Markdown or AsciiDoc-like syntax. Unlike Markdown and others, Duck pages aim to not only allow for quick creation of rich-formatted docs, but also to contain data necessary to integrate the document with the rest of your Mallard-based documents.


Shaun also presented another tool that he has been working on: Blip. It is a web application to monitor documentation projects that use SCM repositories. Some examples include:

Blip lets you not only browse through individual modules in your documentation project, but it also mines data to present information about contributors, their commit or mailing list activity, and much more.

  • An example of a project profile with complete data on branches, commits, authors, included documents, and more: Gnome User Documentation
  • An example of of a user profile with personal stats: Shaun McCance

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