Imagine you’re a new developer tasked with patching a few reported user errors for a video editor your company developed. Sounds easy enough, right? Well, you get to work only to discover that there is no software documentation at all. You’re left entirely in the dark about the reasoning behind architectural decisions.
Situations like this show us the importance of documentation in software development. However, this is only part of the story. Read on as I explore this in more detail and show you how good documentation, indirectly at least, saves lives.
Earn karma points: leave a roadmap
As described above, your work would be cut out for you without proper documentation. As software is developed, it can become quite complex. So while the previous developers might have thought it easy to follow the logic behind their decisions, the new team might not be so sure.
Let me stress this clearly: It’s hugely important to document.
Some may even argue that it’s sacrilegious not to do so (and you’d earn karma by committing to leave documentation).
And:
Documentation helps others, but it can also help you. Even if you think your memory is flawless and will never fail you, there’s a good chance you may forget why you made certain decisions.
So while you should ideally create a main document once the software is relatively stable and critical structural decisions have been put in place, you should also have plenty of inline documentation (like comments) that briefly explain the logic of the code.
Also, ensure that your formal documentation is easily findable (you also lose karma points for making it a “Where’s Waldo” quest).
Skillful software documentation
Now that we’ve gone over how software documentation can help you, the coder next door, and how it can improve your karmic growth, let’s go over how you can take this realization and implement it.
I’ve alluded that software documentation is not a “one-and-done” deal. There are different kinds of documentation. Skilled software documentation involves not only correctly ordering the information, but using suitable mediums as well.
Documentation isn’t just for you: end-user documentation
Software documentation for users will typically include online manuals that can be found on the company website, or it might consist of technical manuals that were provided on the purchase of the software.
End-user documentation should empower the user so that they’re easily able to install, use, and even troubleshoot problems. This comes with the advantage of taking the strain off of the tech-support team.
Just-in-time documentation is another form of documentation that comes in handy for this purpose. The idea behind this type of documentation is relatively straightforward:
End-users get support “just in time,” i.e. when needed.
This might include FAQ pages, how-to guides, or knowledge bases. End users may also benefit from the following:
- Tutorials and other explainer-type videos: cover the more complex features of the software or the software as a whole.
- Release notes: give end users a “heads-up” about the new features and changes they can expect. They can then adapt accordingly and seek support as needed.
When it’s all about you: internal documentation
Now this said, there is, of course, the need for internal documentation (as we’ve gone over previously). Developers may opt to create the following types of internal documentation:
- Detailed documentation for other developers: These instructions assist developers in building, amending, or updating software. This includes explanations of the architecture (such as how the features and components work together) and reference documentation.
- Guidelines: These are more administrative and act as roadmaps for the developers. The guidelines will likely include notes from previous meetings and other relevant administrative information.
How to create excellent software documentation (that saves lives)
Ready to be the hero of the software development world? I can help you with this, but it requires you to take into consideration the following key variables of software development:
- Understand the consumer: No business function can avoid the reality that attending to the consumer’s needs is highly important. This means that developers should have a solid understanding of their pain points. While the software itself should address these, so should the documentation.
- Avoid complex jargon: Documentation written for the end-user should be easy to understand. Remember that for external documentation, you’re writing for the “layman,” not your development team.
- Continually update: After every patch and release, make sure that you update the documentation accordingly. This includes not only internal documentation for the developer but also team documentation, as well as external documentation. Nothing is worse than an outdated manual!
- Get user feedback: With every new release, ask for user feedback. This can help improve the documentation and the software itself.
- Get a second opinion: No man is an island. This phrase rings true when it comes to software documentation. Get other team members to state their thoughts about the clarity of your internal and external documentation.
Saving the day, one readme file at a time
I hope that this article has clarified the significance of software documentation and that you’re now leaving with a few helpful tips and ideas about how to apply effective documentation to your next project. Happy coding!