The most overlooked part in software development - writing project documentation

Software developers like to write code and they like it very much. They tend to enjoy writing exhausting tests and continuous integration/continuous deployment configurations to assure top-notch quality of software. However, most of the time one part of the whole software development process somehow goes under the radar. The most overlooked part is writing documentation. We always tend to say to ourselves that we will write the documentation once the project is finished, or that we will release this version first and write the documentation later. LeBlanc’s law clearly states: Later equals never. I think this requires no explanation, but instead forces us to act.

Where is my documentation?

You are probably already writing your project documentation: writing comments in code, writing project-specific stuff in Google Docs, describing project integrations in Confluence, discussing implementations through communication channels like Slack or Skype. Everything that relates to your project is project documentation and it will be relevant at some point in time, especially after the project moves to support mode.

So, I think we can now agree that you already have your project documentation, or at least it exists in your head. The only problem lies in the scattered locations of the documentation, which at the end of the line makes it seem that you have no documentation whatsoever. This problem can be easily addressed with a unified way of writing documentation that will bring all members of the team to the same page.

There are a lot of documentation systems that will help you out with managing and hosting documentations; some of them are commercial, some are free and open to use. The idea is to extract the list of available systems that are more developer-oriented. Let’s check the compiled list.

Proven documentations systems

Confluence

Although Confluence is a very good piece of software for project collaboration, it somehow repels developers. They are more for having something with more code like syntax, Markdown files, or .rst files.

Let’s go through some documentation systems that are more appealing to developers.

Sphinx

Sphinx came into existence in the Python community, and one of its prominent users is the Python project itself. It was written by Georg Brandl and is licensed under the BSD license. Sphinx uses reStructuredText or Markdown as its markup language, supports multiple output formats, extensive cross references, hierarchical structure, code handling, and built-in extensions. Plus, user-contributed extensions make it the documentation system of choice for a great number of developers both in the Python community and beyond.

MkDocs

MkDocs calls itself a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. It is Python-based. Documentation source files are written in Markdown and configured with a single YAML configuration file. On its Wiki page it provides a long list of themes, recipes and plugins making it a very attractive system for writing documentation. YAML configuration and Markdown syntax make this system very easy to use and customize. You can check the eZ Platform documentation, which is written with the help of MkDocs.

Docusaurus

It markets itself as an easy-to-maintain open source documentation website. It is Markdown-powered, built using React, supports translations, document versioning and document search with the help of Algolia. It is built on Node and was developed by Facebook. The whole range of Facebook’s open-source projects build their documentation with Docusaurus. An example project that is non-Facebook and uses Docusaurus is Babel. It is a well-documented and beautiful documentation system that is worth checking.

GitBook

GitBook is a paid documentation system that is hosted in cloud. Compared to previous systems, GitBook requires almost no time to set up. After the registration it becomes available instantly, providing free collaboration for two users with one private and one public space. GitBook supports Markdown syntax, rich embeds and rich content, and plethora of integrations with third-party services like Slack, Google Analytics and Github, making it the most advanced all-round documentation system of them all. As a point of reference you can check its documentation.

Our documentation platform of choice – Read the Docs

Read the Docs is an all-round platform for handling documentation through building, versioning and hosting it. It is a free and open-source platform, which describes itself as Continuous Documentation. It supports both Sphinx and MkDocs for building documentation. 

Let’s start with a simple configuration and setup.

Setup

Create a separate repo or place docs inside the project repository.

The first step is to install Python’s package manager called pip. Then, if you are adding documentation to the same repo as your project code, create a separate directory called docs to make it clear where your documentation is. In the docs directory create a new file, requirements.txt, which serves for defining dependencies for pip (similar to composer.json in the PHP world) and put the following inside:

sphinx>=1.7.4,<2.0
sphinx_rtd_theme>=0.3.1,<1.0
git+https://github.com/fabpot/sphinx-php.git

Install the required dependencies with:

 pip install -r requirements.txt

or if you run into issues with the pip and you probably will on OS X, try this:

 sudo easy_install `cat requirements.txt`

To ease building documentation, there is also the helpful Makefile:

# Minimal makefile for Sphinx documentation

# You can set these variables from the command line.
SPHINXOPTS    =
SPHINXBUILD   = sphinx-build
SPHINXPROJ    = AcmeProject
SOURCEDIR     = .
BUILDDIR      = _build

# Put it first so that "make" without argument is like "make help".
help:
 @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

.PHONY: help Makefile

# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
 @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

 And at the end of the course, add the required configuration for Sphinx in conf.py:

import sys, os
import sphinx_rtd_theme

from sphinx.highlighting import lexers
from pygments.lexers.web import PhpLexer
from pygments.lexers.web import HtmlLexer
from pygments.lexers.web import JsonLexer

from datetime import datetime

lexers['php'] = PhpLexer(startinline=True)
lexers['php-annotations'] = PhpLexer(startinline=True)
lexers['html'] = HtmlLexer(startinline=True)
lexers['json'] = JsonLexer(startinline=True)

extensions = ['sphinx.ext.autodoc',
    'sphinx.ext.doctest',
    'sphinx.ext.todo',
    'sphinx.ext.coverage',
    'sphinx.ext.imgmath',
    'sphinx.ext.ifconfig',
    'sensio.sphinx.configurationblock']

source_suffix = '.rst'
master_doc = 'index'

project = 'Acme Project'
copyright = 'Acme'
author = 'Acme'

version = ''
release = ''

exclude_patterns = ['_build']

html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

html_static_path = ['_static']
templates_path = ['_templates']

html_theme_options = {
    'collapse_navigation': True,
    'display_version': True,
}

html_context = {
    'copyright_url': 'https://www.acme.com',
    'current_year': datetime.utcnow().year
}

def setup(app):
    app.add_stylesheet("css/style.css")

 Then, let’s create our main entry point for the documentation index.rst file:

Acme project documentation
==========================

This is first page of Acme project documentation.

 Now we have everything set up and ready for writing excellent documentation. All previous steps can be automatically created with a tool that needs to be separately installed, called sphinx-quickstart. You can start adding your pages, text, code, etc. To trigger the documentation build simply run:

make html

My suggestion is to add _build directory to .gitignore file, as it acts as a temporary cache and a storage for build procedure.

Upload docs to Read the Docs

Create account on the Read the Docs website, select to import an existing project and point it to your repository URL. Enable some way of notifying Read the Docs on your repository side, (something like hooks provided by GitHub). You can check out what it looks like on the Netgen Layouts project documentation.

Cherry on top

When you are set up and running, there is one thing you can add to make the whole process of writing documentation a bit lovelier. Not only can your code have Continuous Integration set up, but your documentation can as well. For that purpose, use the well-established Travis CI, which we at Netgen like very much. So, why not give Travis CI permissions to your project repo and create a simple .travis.yml file with following contents:

dist: trusty
sudo: false

language: python

python: 2.7

cache:
  directories:
    - $HOME/.cache/pip

branches:
  only:
    - master
    - /^\d.\d+$/

install: pip install -r requirements.txt

script: make SPHINXOPTS=-nW html

notifications:
  email: false

git:
  depth: 1

And voilà! You are welcome :)

Conclusion

Bear in mind that project documentation is a very important part of the developer experience, whether to an experienced or a rookie developer, and as such is crucial to have and to be easily accessible and used. As I showed you in this blog post, the whole process of writing documentation doesn’t have to be hard, but rather a fun and more developer-oriented process that you probably initially thought it was.