Brussels / 3 & 4 February 2018


DocBook Documentation at SUSE

Automatically Ensuring Quality of SUSE Documentation

In the SUSE documentation team, we have been using DocBook XML for years. But then, even with all our experience and the strictness of XML, we still make mistakes. So we have been adding QA tools to our tool belt which we are presenting in this talk:

  • The SUSE Documentation Style Checker which we use to check for consistent terminology, writing style, correct spelling, "soft" XML rules that don't fit the DTD, and gotchas
  • Travis, the CI tool which you probably know and hopefully love and which we use to make sure our documentation validates when it enters our Git repo
  • dapscompare which we use during the development of our layout stylesheets to check for unintended consequences and for issues with tool dependencies

Using these tools helps us ensure good formal quality, so that human reviewers can focus on the content. It also helps with make translation efficient.


Stefan Knorr