Developer documentation made easy with LaTeX

Developer documentation in software projects

In many projects and prototypes, documentation in text form is a simple way to easily understand some basics of a project and to start off development by explaining key design choices and concepts. There are many ways to provide such documentation, but often a README plain text file is provided. Such plain text might not effectively allow be the most straightforward communication mean; we all know that an image is worth a thousand words. Schemas, UML diagrams, formatted code snippets, color, and other more advanced mediums and media content cannot be easily added and is impossible to present in a concise way. Another way is to use formats such as Microsoft Word or LibreOffice documents. This is probably one of the most convenient way to include additional formatting and content, but strongly lack in the area of versioning where changes cannot be dealt with in a similar way to code. Developers used to version control in software projects can benefit from sharing the same workflow with developer documentation. My solution to all these problems is to use LaTeX whenever possible, and I'll explain why.

LaTeX is a simple language for writing complex documents featuring rich content. It is extensible through the use of additional packages and the usual output format is PDF. It can be versioned exactly like software code and live in a project's repository in its code form. The main difference between LaTeX and MS Word or LibreOffice is its clear separation between content and lay outing. Another great difference is that because a PDF is produced from LaTeX files, the generation process can be personalized and automate various tasks. For example, say a class diagram from a set of classes located in a package is included in the document. Many tools can generate automatically such diagrams and it is therefore possible to do so automatically when generating the document.

Developer documentation can benefit from being up-to-date with reduced efforts from developers when tasks like diagram generation can be automated. Links to certain classes or places in a repository can also be made variable by means of functions and based directly on the code with very little effort. When done correctly and especially for large and distributed teams such as those working on free or open source software projects, developer documentation can help new developers start working earlier and provide insight on key design choices which are led to change in future versions. LaTeX helps delivering these advantages by leveraging the burden on developer to constantly maintain content which can be extracted or generated from a codebase. When they do need to edit the documentation, it provides a simple and effective interface to do so without having to worry on formatting or version management in a different way.

Creating LaTeX documentation the easy way

If you are developing on the GNU/Linux platform, a very popular choice among developers and industries, the environment required for LaTeX is very limited. I like to simply install the "texlive-full" meta-package (package which only provides dependencies on all other TexLive packages) which is available in most distributions. The result is a heavy installation size, but it is one step and you'll be sure to have virtually all the packages you'll ever need. Other popular platforms such as Windows and MacOS will have builds of installable TexLive which are simple, but far from one step of our GNU/Linux counterpart.

The next step is to create a base document. In my case, I use a simple template which is basically this:

If you are unfamiliar with LaTeX, I suggest you read this great five minute guide to LaTeX. The other portion needed to easily work with the document is a Makefile. Mine is usually something like this:

Simply change the texfilename to the actual filename of your main tex document (the one which includes the others, if any). Notice that pdflatex, the tool used to turn the tex document into a PDF file, is ran twice: this is done to get the references right. Running it only once will yield "?" when referring sections (again, if any). The build-run part allows to open the file once built. You can uncomment the line corresponding to your operating system.

The final step to this process is to ignore the unnecessary files produced by pdflatex from the versioning system. With Git, this can be easily done by adding the following lines to the .gitignore file (create it at the root of your repository if it doesn't exist):

Because it can be generated, I tend to ignore the PDF file as well, so that can be added (*.pdf for all PDF files). Some might want to version the file such that it is always available from the repository. This is convenient, but opens the door to having unsynchronized Tex and PDF files.

LaTeX is a solution, not the solution

LaTeX has many virtues, but it might not be adapted to all contexts. For large organizations and multi-disciplinary teams, having to build documents before reading it can be alien and not knowing how to edit a document can be (very) frustrating, especially if you break building of the document or cannot understand the errors it spits out.  The principles making LaTeX a good solution is that it allows for rich content to be included and automatically generated while living and being versioned in the codebase. Any other tools achieving the same goal is as good, and better if it offers a simpler approach than LaTeX does. The main problem with LaTeX, in my experience, is the lack of visual feedback when creating a document. This is even more important when many different media content is present in the document as you don't want to surcharge the page. In a future blog post, I'll present my present workspace and how I use Atom, the editor by the people at Github, to efficiently create LaTeX documents and visualize it alongside. I'll also try to provide some tips on how to write an efficient developer documentation.