In this blog we will focus on software documentation, namely the documentation produced by teams and individuals involved in defining and developing software (architects and developers). There are other complementing types of documentation like requirements, business analysis, etc which we will not be focusing on.
How many times we jump into an existing active project or take on maintenance of “legacy” software, only to find out that documentation is either missing or not sufficient.
This is unfortunately a very common experience for many development teams. Why is this happening? There are a few reasons:
- The pace of software development is constantly increasing to respond to more and more complex market demands. Activities deemed as “non-essential” like documentation and sometimes even testing(sic!) are brushed aside in favor of increasing output of features.
- Documentation is hard to maintain over time as more complex software leads to more complex documentation.
- Diagrams and drawings tend to be very brittle and as software evolves, they too became outdated.
- Developing documentation is also well … boring, most developers prefer to focus on interesting features, improving efficiency, coding.
Software documentation goals
Knowing all the effort and time required to address the above points, let’s ask ourselves: why even bother? Why is software documentation important? Good documentation plays critical role in following scenarios:
- Onboarding of new team members. Every time new developer joins the team, good documentation will help in fast orientation and will not require extensive time investment from other team members to teach good fundamental level of the project knowledge.
- Regulatory requirements and audit. If the software you are developing must undergo external or internal audits or is influenced by any regulatory requirements, then good documentation makes it much easier to work with auditors. Sometimes documentation is even a strict requirement for audit.
- Communication with all stakeholders. Good documentation enables all types of stakeholders to understand software in the context they are interested in. If documentation takes into consideration different types of stakeholders and carefully adjusts wording to be less or more technical, then it saves the team a lot of time otherwise spent on explaining and translating software system properties to everyone.
Software documentation characteristics
Let’s define desired characteristics of software documentation to fit into modern, rapid pace of development.
Simple. Documentation should be simple and minimalistic to decrease maintenance effort and make sure all stakeholders (including new developers) can understand the core concepts.
Holistic. Different types of documentation consumers will require different contexts. Good documentation should account for all stakeholders and make sure everyone can participate and understand. Enabling real time collaboration is another important goal.
Automated. In order to make sure that documentation is maintained over time and there is only minimal impact on development teams, most of the diagrams, charts and specifications should be as automated as possible.
Reusable. Software documentation structure, vocabulary and model should be reusable for any new software projects, so having a structured but in the same time flexible documentation model is very useful.
Portable. It should be easy to generate and distribute documentation independently on any hosting medium. Like with any other software, avoiding vendor lockin might be a concern for your company, so designing the core of your documentation in a way that is portable is a good practice.
In this section we will look at different tools, frameworks and documentation models to fulfill documentation characteristics requirements. We are going to focus mostly on open source tools and standards.
Below diagrams shows tools, frameworks and standards we will use to implement our documentation strategy later on.
Tools and Standards
Now, we will focus on specific tools and standards that can be used to implement our strategy. Please note that there are almost always alternatives to each tool, framework or standard. For simplicity I’m recommending the ones I’m familiar with that I know work well together. You can think about it as a starter pack for good software documentation.
To keep documentation simple, we need a suitable medium. Most documentations nowadays are either in MS Word or pdf, but I believe that Markdown is a better choice. Markdown is a lightweight, HTML-like markup language that is very common in software projects (README.md files etc). It is more scalable and easy for developers to use markdown rather than complex text editors like MS Word. Added bonus is that markdown files can be directly edited in IDEs or code editors like Visual Studio, Visual Studio Code, Atom or WebSharper etc.