Tools for Documentation

Apart from assembling the code, writing the documentation is the most challenging task when developing a library or a tool.

Here are the tools I'm currently using for documenting a library and documenting a tool.

Documentation for a Library

I started first with a text document converted into a PDF. I was using the free word-processing Pages but the generated PDF document had flaws.

The question was whether to have a separate file for the documentation or to include the documentation into an existing file.

The documentation is directly inserted into the header file, and relies on standard keywords as @brief, @details, @param.

embedXcode generates a template with the corresponding parameters for the selected function.

Then each field needs to be completed.

Then Doxygen parses the header files and generates an HTML website, and a set of XML files to be compiled into a PDF document.

Xcode supports those keywords natively, and provides the documentation as Quick Help, here called with the alt-? short-cut.

Documentation for an IDE

Documenting a tool has been more difficult. For embedXcode, I started first with a text document converted into a PDF. I was using the free word-processing Pages but soon the file was too big to handle, especially with pictures.

Additionally, the generated PDF document had flaws, was very large, slow to upload and difficult to share.

The second tool I used was the iBooks Author application to generate an electronic-book shared on the iBookStore. This greatly simplified the way the user manual was published. However, some users heavily disliked the iBooks application (albeit available on macOS and iOS), and some countries did not have access to the iBookStore, so the PDF document was still needed. Just as before, the PDF document generated by iBooks Author had flaws, especially for the internal links.

The major problem actually came from Apple. Apple didn't update iBooks Author very often, so it kept the old interface based on floating palettes when the other productivity tools (Pages, Numbers and Keynote) have those tools grouped on a fixed pane.

More annoyingly, submitting an updated release of the user manual was always risky, as Apple was often blocking the new release for arcane reasons.

Website for an IDE

So I switched to an online only user manual, hosted on a dedicated website.

The entire website is generated by MkDocs, a tool that turns MarkDown files into rich HTML static pages. MkDocs can be expanded with templates and plug-ins, and I'm using the Material for MkDocs template for a clean presentation.

There is one MarkDown document per page. This granularity eases maintenance and speeds the upload to the server. PDF documents are no longer available.