The business risks of overlooking software documentation
Poorly made software documentation can become an expensive headache down the road
The trouble usually starts when a founder or company decides to take their software product–already developed–and switch to another development team.
In the very worst cases, all Team One provides to their replacement is a .rar file and a “good luck!” leaving Team Two to scramble to figure out what to do, or whether to even accept the project.
As unprofessional as the latter scenario may seem, we’ve seen it happen frequently. The blame can get thrown at developers, as they have a reputation for not wanting to take the time to write down their process. Yet it’s the decision makers who are ultimately responsible. If a project’s leadership doesn’t make documentation a priority, it won’t get done.
Documentation is the last thing many founders consider when developing a software product
Without a background in software development, it’s easy to envision documentation in a simple way, like a handy instruction manual given at the end of the project: Something helpful but not essential to a well-developed product.
To compound the problem, those without a technical background might have to outsource 100% of their project’s development. In this case, the topic of software documentation may never enter the conversation. Especially if the development team agrees to a low, fixed-price budget, documentation is extra work they can’t afford to do. It’s in their interest to say very little on the subject.
Or if a dev team does try to advocate for documentation, the owner isn’t always convinced it’s necessary. They look at the budget and see time allotted to these tasks and think the team is only trying to get more money, selling them on an unnecessary extra.
The product gets made, invoices are paid and the owner has no idea if they’ve just bought a lemon or not.
With all of the challenges a founder has to face to get a product into the market, it’s hard to say “Hey, here’s this other thing you have to learn about.” However, knowing a few basics about software documentation could potentially help a founder steer their project away from danger.
Fortunately, software documentation is more exciting than it seems
Software documentation is not just a user manual given at the end of a project. Rather it’s a dynamic process that occurs throughout all stages of development, in planning, development and release.
Documentation is a complete record of how a product was made. It shows the product’s history, explains choices and changes, and gives developers and users instructions.
Essentially software documentation is:
History of a project + Explanations about how the product works
Let’s look at the main types of documentation, as they appear in development stages.
1. Planning Stage
Definition of requirements, high-level design and visual contract
At the planning stage, documentation can be as simple as a list of requirements and a series of wireframes.
Most projects will turn this into a high-level design, where the architecture of the project is decided, as well as the “how” of the features.
Additionally, we like to invest time in making a clickable mockup. After evaluating features, we transcribe them to a design using a combination of Sketch and Invision. Then the client is able to determine if the software will function as intended, and confirm how the features will look and work.
This prototype acts as a kind of visual contract with our clients, so that we are on the same page and features are budgeted correctly. Additionally, it is a blueprint for the product so developers have a precise guide to follow.
Documentation within project management software
During development, project management software helps semi-automate the documentation process. Our team uses a combination of Confluence, Jira and Git. These programs integrate with one another, making them even easier to use.
The best part about using these programs is that documentation ends up being created in lockstep with optimal project management.
Confluence acts as a global collaboration tool. It’s like a reference book for a project, containing the product’s roadmap, requirements, meeting notes, team decisions, and technical documentation.
Jira is the taskmaster. At the start of a project, a product backlog is created, which in essence is a set of tasks. These tasks can be directly pulled from feature descriptions written in Confluence.
Tasks are organized into a workflow, usually a set of sprints (short periods of work), and assigned to team members. As the project moves forward, it’s easy to reorganize/reassign/edit tasks as needed.
Github is the guardian of the code. Git is an application that allows teams to store and update code in a way that shows its history.
Team members upload code to Git in “commits,” along with notes explaining what they have done. Current or future developers can see when and who uploaded each batch of code, and read the developer’s notes.
Developers can create multiple backup points in the code, making it possible to revert back to an older version if something goes awry.
3. Product Release
When a project is finished, there are several types of documentation a product owner should receive. We can think of this as a checklist of the following items:
Code. The code itself is obviously the number one priority, but there is a good and bad way to deliver code.
Ideally, when one team is done with a project, they will fork the code base. This allows the next team taking it over to see the whole history of the other team’s activity in the repository, including all of the versions and developer notes. Otherwise, the new team is locked out of seeing this, and the code is just a file with no history or context whatsoever.
Within the code itself are explanations as well, known as code comments. These are short texts that are for human eyes only, explaining the code’s methodology. Ideally, comments should be helpful and well written.
// I’m not sure what I was doing here. Have fun!
A well-known joke amongst developers is that “good code documents itself.” Truly experienced coders know that software is difficult, and it’s possible to quickly forget important details about even the most elegant solutions.
Records of the work done in Confluence. These can be exported into PDF and other document formats.
User documentation (optional). Some projects may require instructions for users, though not all will.
The benefits of solid software documentation are numerous
- Facilitates communication amongst team members, project managers and stakeholders
- Tracks important changes and decisions
- Cuts down on emails and the need to attend all meetings, as everyone can check the project status via the software
- Makes it possible to easily add developers to a project, since they can be brought up to speed quickly
- Encourages better coding practices
- Leads to faster bug resolution
- Shows who did what, creating a point person for questions or problems that arise
- Enables easier transitions from one team to another
How to know if a team is documenting properly
We recommend always hiring a team with great reviews and references. It doesn’t hurt to ask for contact numbers of past clients to speak with them personally.
When interviewing a development team, ask about their documentation procedures. What programs do they use and how do they organize development? Ask if they allow their clients access to tracking tools in order to observe the project’s status, and find out what deliverables are promised at the end of the project.
Also, if a team rushes through the planning stage or comes back with a quote that’s well below the market rate for their area, this is always a red flag. It can be tempting to go with the quickest and cheapest option, but the reality is that corners are being cut and documentation is usually the first thing left out.
Documentation is not an extra. It’s part of a properly managed software project.
While development teams have gotten a bad rep when it comes to documentation, it’s ultimately a decision maker’s responsibility to include documentation in the process. This requires a small investment of time and money, but pays back dividends by facilitating efficient development and creating a higher quality product.