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
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. |