Stephen Musoke Senkomago Ramblings of a father, husband, tech lover, amateur poet, book lover, who believes family makes him & culture holds all

Documentation, the word that brings cold sweats to techies far and wide, makes product managers roll their eyes but is the one essential ingredient in aiding adoption and usage of software tools and services.

A key mantra for software development and delivery is “documentation, documentation, documentation” while agile purists will take “Working software over comprehensive documentation” to mean that no documentation.

Obviously in today’s world the expectations for clients, is that software is key and must evolve quickly to meet changing needs measured in weeks, and not months. This fast paced change actually highlights the importance of documentation, but places pressures on it to evolve more rapidly, be easier to use and understand, while maintaining a trail of changes being made within a rapidly changing environment.

Many formats have come and gone over time, plain text,  HTML Help, Windows Compiled HTML Help (CHM), Oracle and Sun Help, Eclipse Help, Flash help not forgetting PDF and MS Word documents for printed manuals. The common practice was to use a single tool to develop the help that compiles into multiple help formats.

Fast forward and the model seems to remain the same, however the challenge being what markup language to use to enable generation. In comes Markdown (https://en.wikipedia.org/wiki/Markdown) which aims for readability (JSON, YAML) so that users do not need to know markup but provides a way of formatting with simple conventions. Interestingly at the time of writing this even Whatsapp one of the most popular chat clients uses markdown like formatting.

The formatting challenge has been solved but now how to build the content, version control it to keep track of updates, generate the content and share it with the world. The most common tools are:

1. GitHub pages (https://pages.github.com/) – using a special branch within a GitHub based repository to build online based documentation
2. GitBook (https://www.gitbook.com/) which provides an excellent editor, hosting, build for generating PDF, online documentation, and mobile format (.epub and .mobi). Just open an account, fire up the editor and you are good to go

However if you are using private repositories and need to keep content internal facing, then you need to pay quite a bit for GitBook or jump through multiple hooks. However GitBook fortunately provides a command line client which can be used in this case to build the documentation which is then distributed using internal channels.

The steps to setup a local Gitbook environment are:

1. Install npm
2. Install Gitbook cli by typing the command below

   $ npm install gitbook-cli -g

3. Setup a git repository for the project and add the following files:
   • .gitignore – include the _book directory in which the book will be generated
   • book.json sample below

     {
       "title": "My Book",
       "description": "Description",
       "author": "Author Name",
       "gitbook": ">= 3.0.0",
       "structure": {
         "summary": "SUMMARY.md",
         "readme":"README.md"
       }
     }

   • README.md the default information on the book
   • SUMMARY.md the Table of contents for the book, which may be in different directories recommended is a docs directory

     # Summary
     
     * [Introduction](README.md)
     * [Chapter 1](docs/chapter1.md)
     * [Chapter 2](docs/chapter2.md)

   • package.json – contains build commands for the book

     {
       "scripts": {
         "docs:prepare": "gitbook install",
         "docs:watch": "npm run docs:prepare && gitbook serve"
       }
     }

   • The final project structure looks like
     

     Example gitbook project structure

4. You can view the book locally by running the command below which starts up a server running on port 4000
   

   $ npm run docs:watch

5. Commit the contents to your git repo

I have to say that I love the GitBook Editor which works way better than my IDE, so after commiting the intial files, I fire it up and open the directory containing my project so that I can edit the files from there. Obviously I lose the ability to put high quality comments on what has changed in the files without jumping back into my IDE or git command line, but the sacrifice is currently worth it.

Additional Steps to Generate ePub and PDF

1. Install Calibre (https://calibre-ebook.com/download) which provides the ebook-convert utility
2. Add tasks to the package.json as below:

   {
     "scripts": {
       "docs:prepare": "gitbook install",
       "docs:watch": "npm run docs:prepare && gitbook serve",
       "docs:generate-epub" : "gitbook epub ./ ./_book/mybook.epub",
       "docs:generate-pdf" : "gitbook pdf ./ ./_book/mybook.pdf",
       "docs:generate" : "gitbook build && npm run docs:generate-epub && npm run docs:generate-pdf"
     }
   }

3. Generate epub by running the command
   

   npm run docs:generate-epub

4. Generate pdf by running the command
   

   npm run docs:generate-pdf

5. Generate both epub and pdf by running
   

   npm run docs:generate

UPDATE: More information on the GitBook Toolchain  can be found at https://www.gitbook.com/book/gitbookio/docs-toolchain

UPDATE2: Added steps to generate epub and PDF documents

UPDATE3: Discovered that the process has a name – Documentation Driven Development, which is pretty interesting concept … https://twitter.com/brnnbrn/status/847197686042312704/photo/1