Felix Kerger - Lessons learned: Choosing your documentation system

How to choose a system for internal documentation if you have a relatively small writer team that should serve a large number of users? What if your internal APIs aren’t documented at all? Or what if your documentation platform couldn’t address your needs anymore? Documentation easily becomes outdated. How can you meet the expectations of your users? Felix Kerger tells a story about their journey of how the DevRel team tackled these issues at King.

Strategy

1. Define exact requirements by making a list of:
   • Must haves: all the features you need
   • Nice to haves: things you’d like
   • Dreams
2. Spend enough time to learn about and try-out existing solutions
3. Use each one a bit to get to know them
4. Compare your experiences to your list
5. Select the best fitting solution

Our requirements

• Documentation needs to be next the code: ideally in the resource files top or below the method
• Code samples to show how to use the methods: ideally part of a test suite to stay up-to-date
• Be able to display and handle different versions of the APIs
• Every method should have its own page
• Use CSS for styling

Tried the existing solutions' fit for our needs

Doxygen

• Pro
  • Can extract the documentation from C++ or Java code
  • Easy to set up
  • The default generated result is useful as it is
  • Well know
• Contra
  • Doesn’t support convenient version control solutions
  • Takes a lot of space
  • Not customizable enough

Read the Docs

• Pro
  • The default look and feel of the generated documentation looks good enough
  • Supports versioning and hosted services OOTB
  • Can use simple templates and CSS style to customize the look
• Contra
  • Doesn’t have direct support for C++
  • Making version controlling work as you want can be challenging when you need to host the service internally

Breath

• Pro
  • Similar to Doxygen: can parse C++ OOT
  • Easy to set up
  • You can combine Breath with Read the Docs
• Contra
  • Hard to edit the generated result
  • Takes a long time to get the result

WebAPI (Swagger)

• Pro
  • Widely known and used
  • Easy to set up and update
• Contra
  • Not meant for C++ code, it’s for a completely different ecosystem

Lessons learned

• Each tool and solution has strong points
• None gave a general solution to all our original needs

Building a custom solution

Ideas of the features that must be developed in-house to generate HTML output from C++:

1. A C++ parser that could extract the Doxygen documentation code from the C++ code
2. A custom HTML generator to store the extracted documentation
3. Doxygen to generate a default HTML output, then use a custom solution to modify that output

Lessons learned

• C++ is complex and ambiguous: developing our custom parser is too much
• Maintaining a custom HTML generator and keeping it always up-to-date is similarly challenging
• Modifying an existing HTML file is a lot of work, and if a new version of Doxygen would render the output slightly different, that could break the documentation on the site.

If you can’t select an existing tool, and developing your own custom system is also not realistic, what can you do? Break down the original problem into components and build up a toolchain that combines existing and custom solutions.

Finding a path forward

From where: documentation stored next to the code in C++

To where: generate documentation in HTML to style it with CSS

1. Doxygen generates machine-readable XML from C++
2. Custom Python scripts create an SQL database from the XML data source
3. Jinja (a templating engine for Python) uses the SQL database and gives a ReStructured Text (RST) file as an output
4. Sphinx (a Python-based documentation generator) creates HTML from RST

Lessons learned

Even if you follow a well-defined strategy, in 90% of the cases, you won’t find an ideal tool that matches all your expectations. You have to decide:

• If you have the time, the resources, and the willingness, you can create a custom solution
• Otherwise, if you find a solution that can meet 80% of your expectations, maybe consider that good enough

The result

• Still not completely done
• Using a lot of components can be a bit messy
• Requires a lot of test to make sure it stays correct
• Highly customizable pipeline to generate HTML from C++
• All is automated on Jenkins build server
• Integrated with GitHub to preview changes
• Addresses all the original problems and needs