How to Manage Software Documentation in a Good Way

26 December 2018

I believe that documentation plays a vital part in any software project. In reality, however, during my involvement in different projects of large corporations, their documentation quality is far beyond the established open-source projects. Several times when I join a software project, the documents are not structured and spreads in different places. Even worse, a company has established different internal wikis for a project because the team from different departments cannot agree with one wiki platform.

Why do we see bad software documentation?

In my opinion, the root cause is the lack of awareness and experience of the project leaders to manage software documentation.

So why is the project leaders take the responsibility? It is because

  1. they are the project leaders who did a selection and have chosen their software experts, and
  2. they decide the development process model,
  3. at least they are capable to point someone who takes care of it, including the documentation concept if they don't have any idea.

Indeed, in reality, I've heard that many managers and project leaders complain that their developers cannot or do not want to write the software documentation of their written software code.

Moreover, many project leaders in a corporation nowadays, have collected their main experience from the year between 1995 and 2010 when the software projects were not so complex as current software projects. Their tools to write documentation were/are Microsoft Words and Excel which can create a doc/docx/xls/csv and pdf files or a simple editor-like Notepad which creates a txt file. After finishing the documentation, they just spread the files in different folders. This workflow can be getting worse since a manager or someone will need the documentation and he/she will copy the documentation to his local notebook or another folder in the company network. We can imagine what will happen if these files don't have a version history.

They may never write a wiki article and don't realize the power of versioned, navigated and searchable wiki-like documentation. Thus, how can we expect them to make a documentation concept and management at this time?

The next part is the mindset of the software developers. An experienced and good software developer will never complain to write documentation of the software that has been written by him/her. Why? Because it is for their own interest to deal with a complex software project and to work effectively. Even though it can support indirectly their moods during the software development. Saying that someone don't have time to write documentation means that either he/she is not good enough for the position or the project team (incl. the leaders) chose an inappropriate documentation concept that cannot improve the workflow. A project leader can apply a standard for the development process, but if the people in the team don't have the mindset, they will hack the standard.

How about the software complexity? Should we blame the software that it becomes more complicated? I don't think so, since the demand is getting higher, the software will evolve to fulfill the demand.

So how can we improve the documentation in our projects?

I would recommend these six steps to increase software documentation in a large project:

  1. Utilizing the documentation generator tool, such as Doxygen for C/C++ and Sphinx for Python.

  2. Clasify the documentation types, such as:

    • user guidelines,
    • developer guidelines (how-to) and
    • software documentation (commented code).

  3. Centralize and deploy the documentations in a server as a wiki-like documentation platform which supports

    • search field,
    • good navigation,
    • access control and
    • team collaboration.
  4. Iteration, iteration iteration! Never expect that someone writes a perfect documentation at once. Always support and embrace the team to write and review the documentation at any time. Plant a mindset in your team to maintain the documentation.
  5. Automate it by utilizing the version control system and integrating into the continuous integration system (CI).
  6. Employ developers which know how to write a documentation with one of these formats: Markdown, restructuredText, WikiText, AsciiDoc.
Back to Blog