What’s up, Doc?

I am not sure whether Bugs Bunny was refering to documentation but we shall assume it does for this post. Documentation can be a dreaded or loved term which may require a carrot or stick approach to get it done, but the method to create and manage documentation can have an impact on whether documentation is written. If documentation is easy to create and manage it is one less barrier in doing it.

What to document?

Off the top of my head there are a number of reasons for documentation:

1. The “hit by bus” scenario where your mission critical tasks need to be understood by someone else.
2. User documentation to reduce support calls and where to point users (e.g. read the manual!)
3. Aide-memoire (comments in code etc.)

Why document?

Quite simply, the types of documentation can fall into reducing risk to business (business continuity), managing resource better (less time answering the same support call), making your life easier (less things to remember and repeat – you are your own user!)

Where to document

Documenting any mission critical tasks should be achieved in any format, it tends to be a small userbase of potential readers and having a folder of Word documents would suffice. Where we have recently hit issues is where to record user documentation. This can change quite frequently (new version of software) and require a number of authors to contribute.

How to document

Having already mentioned one solution to documentation is to have a folder of Word documents, there are a number of possible methods:

1. Word document kept in folder – new versions just change filename appropriately.
2. Wiki site to allow easy browser access to content.
3. Document repository system to store revisions and prepare content

We could say that Wiki and Document repository are very similar. I see them as different since a Wiki tends to hide the repository whilst a document repository makes the repository central in how it works (and tends to be stored along with code). Having looked at the above options, and ruling out Word documents in a folder as too cumbersome, and Wikis tended to become hard to navigate and stored seperate to useable code, we instead look at a document repository, in particular a common system called “Read the Docs!” that is open-source and used in many open-source projects. Lets look at it closer.

Read the Docs!

The system is based on Django and to install your own server can be as simple as downloading the server and running the command to start it up. We performed the following:

1. Installed a modern version of Latex from http://www.tug.org/texlive/
2. Python was installed as described in https://docs.readthedocs.io/en/latest/install.html
3. Setup Nginx server to host the site.

Hosting our own server allows us to use private documentation repository. We managed to get a working server up and running within a day and have been tweaking settings and exploring options. Modifying text files and creating a easily navigatable documentation system allows us to try out new ways to format our documentation and hopefully help us provide a better way of delivering our documentation to our users.

Documentation format

Finally one aspect is what format the documentation is kept in. Read The Docs uses ReStructured Text (or RST) to format the text. For example:

Welcome to ARCCA User Documentation!
====================================

This site hosts the documentation for users of ARCCA services within Cardiff University.  It is divided between the main service being Raven and the workflow managers we provided.  Raven has a getting started guide, along with the dedicated application guides.

.. toctree::
   :maxdepth: 2

   raven
   workflow
   advice
   faq

.. Indices and tables
   ==================
   
.. * :ref:`genindex`
   * :ref:`modindex`
   * :ref:`search`

And there is functionality to help with table of contents and including other files to allow easier access and navigation. The underlying system also converts to a number of different output formats such as PDF or Ebook.

That’s all folks!