Blog.

This Is Why Most Software Engineers Don’t Write Documentation

This Is Why Most Software Engineers Don’t Write Documentation

More than skill set, it’s actually due to a lack of good documentation tools

Photo by Sigmund on Unsplash

No matter whether you work in a small startup or a big corporate company, the odds are that when it comes to good, valuable documentation of your services or projects, there will be a huge gap and need for it.

This can impact multiple parts of an organization, from discussion forums to decide the best path to a goal to the onboarding of new colleagues that need to ramp up their knowledge about how your systems are structured and communicate with each other.

But if everyone feels this problem right on their skin, why on earth does this still happen these days?

Why Is Documentation So Important?

Meetings

If you have ever been involved in discussions of a new, upcoming project that the company needs to figure out how to fit into its current codebase, you know the number of ideas, suggestions, and solutions that are analyzed during those meetings. This number increases exponentially depending on how many people participate in the meeting.

Each proposal for a solution usually comes with its own pros and cons discussed in the meetings.

Now imagine that you ended the meeting and went off to do your day-to-day work (code a feature or whatever). Do you believe that you will be able to remember the proposals discussed, the pros and cons of each one of them, which ones were discarded, and why — or even why a given decision was made instead of another, when someone asks you after a few weeks/months? Do you really think you will be able to provide those answers?

You won’t. And recognizing this “weakness” doesn’t make you look bad — quite the opposite. Knowing your weaknesses is what makes you strong. That’s the only way to fight to minimize their impact.

So what should you do to avoid that one hour of your life, of your colleagues’ time, and of the company's money going the drain? It would be best if you documented the meeting.

Creating meeting notes that are available for your peers to consult if they need to is an excellent way to keep track of what happened there. You can take those notes during the meeting or right after it. Don’t let too much time pass between the meeting and the publication of your notes. Otherwise, you won’t be able to remember half of what happened.

Make sure to write down the main talking points, the proposals that everyone discussed, the pros and cons of each, decisions taken, and action items.

Time travel

A very philosophical title, but not entirely false.

If things go right and your business grows in terms of new needs, a decision you made one year ago is likely to turn out to negatively impact the new need.

At this point, you will need to justify to upper management why things went the way they went. Guess what? You won’t remember.

If you have the record of the meeting when and why you made that decision, you (and your managers) will remember you made that decision due to a strict, time-bound deadline the company had to accomplish, or for any other reason.

Debating ideas

When working at the office (oh, the good ol’ days), it is common for engineers to discuss ideas around a whiteboard, where we draw and explain what we are suggesting. This is often made through UML diagrams.

If you are fortunate enough to do this still, take a few photos of the board before leaving. You don’t want the next team using the board to erase what took you two hours of discussion with another five people.

But what if you need to do this and you are working remotely?

Well, when I faced this problem for the first time, people just tried to explain what they meant using words. The problem with this is that natural language is subject to interpretation and what I understand from a given sentence might not be exactly what you were trying to say.

My recommendation for this case? Use any drawing or UML tool and share your screen. Let people see what you understand from the conversation and put everyone on the same page on the conversation.

This might look slower at first sight since you need a few seconds to draw what people are saying, but it will make communication much more effective because we eliminate at least part of the interpretation gap.

Onboarding

Ramping-up a new team member is always a challenge. You need to get back to the basics and explain what your system does and how each puzzle piece fits the overall architecture.

If you need to do this every time someone enters the company, it can be a time-consuming (and therefore money-consuming) activity.

If you have documentation explaining your system’s basics, it may help you provide some autonomy to the newcomer.

Be creative! If done right, creating an induction plan can spare you a lot of time to do your other tasks, and, typically, a plan doesn’t need much upkeep.

Design some diagrams and schemes that visually show how things work. Make a video. Use this task to also improve something in yourself.

Designing Is Not Only for Software Architects

If you worked most of your career in a big enterprise, designing systems and how they communicate with each other wasn’t a big part of your job description. Your company had software architects that did this work. Instead of writing lines of code, they designed lines and arrows, pointing out how you should build services.

There is a temptation to lie back and rely on their documentation. The problem is that your architecture team’s documentation will be more of a macro vision of your systems. It won’t have specific logic of your boundary or service. You and your team are the ones who know how it works on a micro level.

Extend the existing documentation by providing more detail. Those details can be the difference between making a good decision and making a bad one, which you will only discover months into the future.

Plus by doing this, you will be training your architecture and system design skills, which is always a nice thing for any software engineer to have.

Most Design Tools Suck

Let’s talk about system design tools, shall we?

Most tools I’ve come across are extremely visually driven. What do I mean by this? Most of them require you actually to draw lines and boxes to express what you want.

There is too much concern on how things look, as opposed to focusing on a diagram being easy to create, change and maintain.

If you design a class diagram, for example, on Draw.io, you need to search the items you want, drag and drop, and connect and write its meaning. You will need to be aware of whether the lines look good and if you can correctly understand them. You need to check if the diagram looks “good.”

Draw.io. Retrieved from BlueSpice.com

Let’s say you need to change this diagram and add more components. To do so, you will need to rearrange everything to fit and make sure the diagram still looks good. Multiply this by the number of times you need to update your diagram.

Tools like these are not made for developers. They might be useful for product managers, designers, and upper management but not for developers since they don’t consider our natural laziness, which makes us build things more efficiently.

However, there is at least one tool that is built differently.

PlantUML

My first contact with PlantUML was in college. We needed to design some diagrams, and the professor required us to use this tool. At the time, we never used anything like that. The main tool we used up to then was Visual Paradigm, which is another visual tool.

At that time, I was not too fond of PlantUML. Why? Simple: I didn’t know the syntax and how to use it. Now, I’m very thankful to those professors who introduced me to this awesome tool.

Ok, we get it. You like that tool. But what makes it different from the others?

Everything.

For starters, you don’t draw anything. You write code. Code that is compiled and has an image as an output. This allows you to design things faster, copy examples from other diagrams, and adapt them to a new one to keep version control.

Example of code and output sequence diagram

In the image above, you can check an example of a diagram I made for my master thesis dissertation, where I have a sequence diagram for calculating the price of a service. As you can see, I have no instruction to change the visual of the diagram. I state the interactions between each component. Everything else is up to PlantUML to take care of.

I kept this code in a Git repository, where I can keep control of the changes, accept merge requests for updates, and manage it as any other piece of code.

The Future for Software Engineering Documentation Tools

I really believe that if we want developers to produce documentation of what they do, we need to have more tools like PlantUML. We like to code. And wasting time messing with little boxes and colored buttons is not something that fulfills any of us.

However, even with PlantUML, there is still room for improvement. One of the things that annoyed me the most while using PlantUML was that there was no way of having multiple pages accessing the same code to compile the UML. I needed to replicate the code through different pages, and every time I made a change, I needed to update every page. Having a page access a Git repository with the code, download it, and then compile it and generate the image would improve the maintainability of these diagrams even further.

Also, the images generated by PlantUML look completely old-fashioned. I know I said that developers don’t care about visuals, but come on… We are in the age of material design, not HTML 1.0.

With these two points sorted out, developing new documentation would be a blessing, turning a monotonous task of dragging and dropping into having fun while coding diagrams.

A Matter of Mindset

As most things are, understanding the value of good, up-to-date documentation is tightly linked to one’s mindset. If we are not used to doing this, it will be hard to change habits.

Start creating documentation for things that you find useful. Share it with others. Little by little, encourage others to do the same. It’s not possible to have everyone doing their own documentation, but we need to start somewhere.

Build this mindset where you acknowledge design and documentation as a part of software development. Be an ambassador of this way of thinking among your peers.

Thank you for reading my article.

If you have any questions or subjects you would like to discuss further, please leave a response. I’ll be happy to talk about them!