Why Developers Write Horrible Documentation and How to Solve It

I am a developer and I hate documentation.

This sentiment is common among the developer community. Surely everyone tries to be a good software developer... but honestly, documentation is nobody's favorite thing to do.

The era of complexity started way back when software became a reality. It was all easy at the outset, but the real problem started when users started using the software (well sure, it was intended for them, but still). New team members who need to understand the product also added the need for documentation. For new team members joining in software development roles, proper code documentation and introduction is the only way to get started.

Writing, on the other hand, is a severely ignored skill around the world. Many students and professionals find it hard to construct well-structured sentences and paragraphs. An interesting article on SmartBear discusses the positive impact of writing for Software developers.

However, in the world of Silicon Valley or other IT hubs, documentation is probably the most hated aspect of software development. It is so hated that sometimes software developers find strange reasons not to document their project.

There can be multiple reasons for the strange behavior. Let’s discuss them below.

Why Developers Write Horrible Documentation

Horrible documentation is a common scenario in most of the software development projects. There can be many reasons, both logical and non-logical for poor documentation. What makes it tick? Let’s learn it more deeply.

Developers Are Too Close to the Projects

This may sound romantic, but the truth is that most developers are too close to their project even to write documentation for it. A piece on Writing Assist discusses the impacts of the close relationships that hamper writing documentation. The impact is from the viewpoint of other team members, end users, or the company they are dealing with—the devs aren't thinking outside of themselves, and thus aren't explaining things clearly enough to the readers. Even though this point may be challenged by some skeptics, it is hard to deny it completely. The intricate relationship devs have with their code can sometimes cause them to write poor documentation because they are in a position where they understand what's going on and take for granted the need to explain things as clearly as possible.

No Urge to Write Documentation

Many developers do not feel the need to write documentation. On the contrary, there is always a way to approach a problem, be it writing or programming, but that is not the case here. When insisted to do so, these developers write horrible documentation as they are simply not interested in the task. The end result? Unhappy developers with terrible documentation that only they can understand.

Developers Don't Need Documentation

The idea is the byproduct of the first point. If you are a developer, then you probably know the reasons behind this type of thinking. It’s simple. Developers understand what they are working on and that is why they choose to skip the documentation. Sounds reasonable, right? However, the same developers might forget the intricacies of their own work when they visit it after few weeks, months, or years. Furthermore, without proper documentation or comments in their code, both maintenance and communication end up taking a back seat.

Documentation Requires Time and Effort

Writing is not an easy task; it requires critical thinking, patience, and effort. For developers, documentation can be a chore. According to many, it is just a waste of time and effort as they already know that it requires significant time to produce good documentation. Developers prefer to use this time and effort in implementing new features, solving problems, or squashing bugs.

Pressure to Deliver the Project on Time

There is always a due date hanging around the corner. The developer needs to deliver the project on time, and no one cares about the documentation. The company wants to deliver the project as soon as possible because of the client’s requirements, and the first thing that goes down the drain is documentation. The only exception is when the client explicitly mentions the need for documentation.

Programmers Are Lazy

Even with enough skills to write good documentation, many programmers opt not to write it. Sometimes the reason is pure laziness. There is not much to ponder about the point, but it's those programmers who are simply motivated by paychecks who are the biggest culprits of not engaging in these activities that don’t yield them more money.

Development and Writing Are Two Different Skillsets

So, imagine you are a developer (if you're reading this, you probably are) and like to program stuff. It requires logical and spatial reasoning—traits that are often more mathematical than anything else. Writing, on the other hand, requires some similar traits, but they manifest quite differently. In short, writing and development are two different skills, requiring different mastery and thought processes.

According to an interesting article on Atlantic, the author Bernard Meisler writes, “Most engineers can't write a single coherent sentence, never mind string together a paragraph. Poor documentation is the bane of my existence.” Well, that’s often true for many of the developers writing their own documentation out there.

Frequent Source Code Changes

Agile development is the new way of development. It is fast, unforgiving, and doesn’t encourage documentation. The reason is simple; the code changes too frequently to be documented and hence leads to either poor documentation or no documentation!

Hubris

Hubris can lead many developers to believe in not commenting or documenting their work. Even with a great capacity to write documentation, many programmers opt not to write documentation at all to show their skills and deny their responsibilities for others to understand their code.

Devaluing Self

This point is the complete opposite of the last one. Many developers who are capable of writing documentation don’t do it because they feel they are not good at it. Quora user, Daniel Beck, a technical writer speaks about how developers just take themselves out of the equation by thinking negatively.

My writing's not good enough. My English is poor. I hate writing. It's not my job. Nobody reads the docs. Writing docs isn't as important as writing code. I'm busy.

These are some of the common things devs tell themselves—if they are thinking like this, then of course they'll have trouble writing.

What is the Solution?

With poor documentation being a big problem in the current industry, Livecoding.tv platform focuses on providing a new way of handling the issue. Livecoding.tv is a social coding platform for broadcasting live product development. Any team can utilize the platform to record their development process and make it private for internal usage only. Open source projects can further benefit from the platform, improving the collaboration process.

So, how does it handle the current documentation woes? Video documentation is the answer. The developer records his work, only to be explored by other team members or a potential technical writer that works on the project documentation.

Video documentation is a better approach than written documentation as it requires no extra effort from the developer. All the stages of development can be stored in video and accessed whenever needed. The good thing is that new team members can quickly pick up the project with recorded video cues and proper help from other team members. Overall, the idea is to improve on the drawbacks of written documentation.

On the other hand, the team or company can give the videos to a technical writer to write documentation for end users which also saves time for the most part. The approach is also ideal for agile teams that frequently change their codebase.

Video Documentation Benefits in a Nutshell

1. Removes the need for proper written documentation for internal team.

2. Provides an excellent opportunity for agile teams to keep track of the changes.

3. Helps technical writers to understand better.

4. Saves effort and time for developers, enabling them to divert their energies toward writing better code and implementing features.

5. Can be used to understand workflow mistakes of team members and improve productivity and efficiency.

Are you one of those developers who does not like writing documentation? Please share your comments and let me know your opinion on written versus video documentation.