Developers Who Code Well Suck at Documentation

The developer community is mostly filled with two types of developers: One that does not document their software and technology, providing no scope for others to learn and implement it quickly; and the other that wants to use the technology, but instead of referring to the documentation, ends up on Stack Overflow or Reddit, in a bid to find the answer quickly.

Dos and Don’ts for CTO

Think like a CTO of a company. If you have built an amazing product, the rule of thumb should be to properly document everything. Everything that you don’t write is equivalent to wasted resources and loss of productivity of the employees. Why does it happen? Laziness.

In 2021, the research paper Addressing "Documentation Debt" in Machine Learning pretty much sums up the problem of poor or absence of documentation entails in the ML community. Documentation debt is exactly what it sounds like -- a tradeoff developers make to achieve some sort of short-term benefit, and then bearing the brunt for no documentation later on when trying to explain or build again.

What happens then is that other developers, who are using the software and are frustrated with the technology, end up going on Stack Overflow or Reddit to seek help. Given the much discussed “toxicity” of these communities, the users get replied like “RTFM” or “Read the f**** manual". This makes matter worse for them as there’s no documentation to read it up. 

But on the other side, there are a lot of developers who just don’t want to read the documentation. Even if the developers have created documentation for their software, they go directly to the online communities in an urge to find the answer quickly from someone else, instead of reading the tedious documentation.

Obviously, both of these are not the right way.

What can be done?

Documenting what developers / companies are working on is understandably a tedious process. In a blog, The Surprising Power of Documentation, Vadim Kravcenko narrates the right practices to follow while working on a project and writing the documentation.

Kravcenko explains through an example of a meeting. Every meeting that you hold to discuss the problems in an algorithm is “a missed opportunity" that could have been used to refine the system, if there was enough documentation. Think about it like the time spent on properly documenting the work that could be used for people working on the algorithm years from now, could save a lot of time for everyone, instead of going over to community platforms or holding meetings to discuss it.

The same is the case with the open-source community. There can be a lot of repositories and GitHub that everyone can use. But a lot of developers would say, “It’s closed source if there is no open documentation.” Clearly, if there is no explanation for the implementation of the model, there would be no use. 

What tools to use for “good” documentation

With new LLM-based models like ChatGPT, there is probably no excuse left to not do documentation. It is easy to say that documentation is important, but there should be tools that make it easy for everyone. This also changes with every programming language. For example, according to the discussion on HackerNews, developers appreciate the way documentation functions in Rust. It involves writing markdown within a special type of comment placed above the module, function, datatype, or method that you want to document. The documentation can then be automatically generated from this markdown. 

One of the main challenges in keeping documentation up to date is the increasing complexity of linking the code you're documenting to its corresponding location in the documentation. However, Rust's approach of embedding documentation within the code elegantly addresses this problem.

For the Python community, Sphinx document generator offers great help. Documentation is often left out because it takes a lot of time when working on a project. Simply, Sphinx takes the .rst files and converts them to HTML with just a bunch of commands. Most Python libraries like Django, NumPy, Scikit-Learn, and Matplotlib use it for documentation. 

Is there any excuse to not document?

“Documentation is where I go to find out the mental model behind the software,” said another user on HackerNews. On the contrary, a lot of people argue against spending time on documentation. One reason is obviously laziness, the other is that they often find the other documents meaningless, filled with "garbage". 

Now with LLMs, up-to-date documentation does not require any superpower. This can also boost many companies to a whole new level. But wait, what about overdocumenting? There can be documents running into hundreds of pages narrating things that could have been done in a single line. This is why sometimes people still prefer going to online communities to discuss the problem. 

Moreover, a lot of papers with a lot of code does not bode well for the community. Anyway, a lot of research papers these days do not include any code as it is met with a little hesitance and resistance, some even call it dumb. 

Ultimately, the point is that “good” documentation takes a lot of willingness, resources, and time, but pays off like a compound interest. “If you are building a tower, the documentation is at the foundation.” So, in the end if you have proper documentation, you can tell someone who asks you about your software to read the bloody manual!