The ROI of Documentation

Photo by Annie Spratt on Unsplash

Documentation has a bittersweet flavor for many Engineers, even though many acknowledge the benefits of documentation people usually don’t like to do it.

I respect that, as Engineers, we like to get our hands dirty, built new software, refactor existing software, everything but documentation, no one has time for documentation many might say.

I like to think of documentation as an Investment, when we invest time and effort into making strong documentation, that documentation will pay interest over time for sure, we can call this the Return on Investment of Documentation.

The Return on Investment of Documentation comes in many ways and the goal of this article is to show you my views on documentation, and what is important in order to maximize the interest your documentation will pay you back.

Let's start by looking at the most obvious and simple interests that your documentation will pay off, when you document something you are consolidating the concepts of the document, thus increasing your knowledge of the topic. Details matter and there were many times where I only noticed small details missing in the implementation when documenting it, otherwise, I wouldn’t be aware of these details and they would be left out of the final solution, it helps me gain another perspective.

The documentation should be well-organized and the single source of truth, if these are obtained it will save lots of time for Engineers searching for information and my friends, as we all know, time is money.

So this will enable other Engineers to find the information they need by themselves quickly and will enable you to save time when someone comes to ask about a certain topic, if you have the documentation for it just pass the link, this way you save time and don’t repeat yourself every time someone asks something regarding that topic.

Finally, just like the goal of this article is to share my knowledge with you readers, documentation will also share knowledge within your peers in your organization, and that is crucial, the knowledge within an organization should be as clear and accessible to everyone as much as possible.

At this moment you may already notice that there is, in fact, a big return for the time one invests in the documentation and this return comes in many ways, as Engineers what we want to achieve is the maximum return per time invested.

As Engineers, we all like to cut time and be as efficient as possible, and we are well-known for effectively using tools whenever that saves us time, lets look at an awesome tool that has already saved me tons of time when writing my documentation.

This tool is called PlantUML, it is an open-source tool allowing users to create UML diagrams from a plain text language. It is really simple to use and VisualStudioCode has already a plugin for its integration, this documentation on steroids, who won’t love that instead of spending hours in an editor arranging your class diagram lines to make the diagram pretty enough?

In the snippet below we can see the code and the respective output of a very simple class diagram:

class Student {
int StudentId
string FullName
string Address
string SchoolYear
class Family{
int NumberOfMember
string LanguageSpoken
string CountryOfBirth
class Father{
string FullName
Date BirthDate
class Mother{
string FullName
Date BirthDate
Student --> Family
Family --> Father
Family --> Mother

This is just one simple example of what this tool has to offer but the possibilities are endless and one of the biggest advantages of using this tool is being able to add the diagrams definition on a source control repository, this will ease its maintenance a lot.

Last but not least we have the concept of Living Documentation, this is something that, in my opinion, is crucial for the documentation success and return on investment maximization that is keeping your documentation alive.

This is a very common mistake, we write documentation when implementing a fresh new feature but then we just forgot about it, new updates to the feature are not documented which leads to the document became rotten and stalled. Outdated documentation is as good as no documentation at all because since it doesn’t reflect the actual truth there is a possibility of misleading the reader.

I cannot stress enough the importance of maintaining your documentation updated, it will be hard in the beginning but it will grow on you believe me and soon you’ll be recovering the time you invested in documenting instead of losing that investment because the document became outdated.

Winding up, at the end of this article you now know what are, in my opinion, the main benefits of documentation, the core characteristics of documentation, one tool that I use to help me with my diagrams, and how important it is to keep the documentation updated.

I won’t lie, I didn’t always advocate documentation, but it started to grow on me when I started to see the benefits of good documentation, how it saved me time and allowed me to share and retain knowledge more efficiently.

Those benefits are the interest returned from my investment in Documentation, and as any investor, I want to maximize what my documentation pays back to me. This is the Return on Investment of Documentation.

Nelson out!

Tackling big problems with simple solutions. Software Engineer @ Farfetch

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store