Image by Editor

Documentation is one of the tasks programmers dread the most. I mean, we are programmers and not writers anyway. It is well-known that programmers are great and writing code but could be better at explaining their thought processes.

That's why we hate writing documentation so much. We need to explain our thought processes in words for others to understand. And that's always a challenging task.

Regardless, all programmers know the importance of good-written documentation and its importance to any coding project's success, whether intended for open-source or as a provided project within a team.

Documenting the writing code steps and the justifications of some design decisions are beneficial for people using the code and those who wrote it when it's time to add/remove new features.

In software engineering, writing documentation generally refers to the process where the programmer of the leading code developer writes a script explaining in detail what the code does, its goal, and how it achieves that. The main reason programmers hate to write documentation is that, as a programmer, you would instead write code than an explanation of it.

Make a Roadmap before you Start Coding

This may suppose people to read, but draft the roadmap of your documentation before you even start to write your code. This will help you in two ways, it will make it easier for you to know what to add to the documentation and will be your guide when you start writing the code.

What I mean here by "roadmap" is the skeleton of your documentation, as in the different sections you will explain. For example, if you look at the documentation for Matplotlib, it has four main sections, the installation, learning materials, 3rd party packages, and how to contribute to the source code. Within these sections, there are further subsections with more details. 

Draft as you go

Once you have your documentation skeleton done and start writing your code, try writing both the code and the documentation draft in parallel. I know that most of us, data scientists, would say, "I will just write the full documentation when I am done with the code" though I understand the thought process behind that (which is to focus on the code writing), I think it makes writing the documentation more of a hassle.

Drafting the documentation as you write the code will help you make sense of the decisions you made along the way, what worked and what didn't. In the end, when you're editing and finetuning your documentation, you can either choose to keep what didn't work as a way for others to see how you got to the final product or skip that part and focus on what worked. Personally, I like to keep what didn't work because it is as important as what did work.

Use your Comments as Hints for Further Explanation

Comments are critical for different reasons, but they are not replacements for complete documentation. I like to think of the comments or the docstrings in the code as the headlines of what the part of the documentation that will explain the different functionalities of the code. The comments will give the user the minimal information they need to be able to use the different functions and/or classes. At the same time, the documentation will elaborate more on how the function works and some use cases for the said function. 

Write more Readable Code

Do you hate writing lengthy, detailed documentation? I have a solution for you, and if your code is well-organized, clear, and well-written, you won't need lengthy documentation to explain how it works; a few examples and tutorials might do the trick.

In a previous article, we talked in-depth about how you can make your code more readable. Fortunately, writing readable code is a skill that can be practiced until mastered.

So, more readable code leads to shorter documentation.

Read more Good Documentation

If you want to learn how to write good documentation that is clear, concise, and to the point, read more good documentation. Here, I mean read with the intention of learning the style and process of writing good documentation rather than collecting information about how to use the code. 

Some of the best documentation I read were the Matplotlib, Pandas, and Numpy documentation. Both are clear, concise, and well-organized. As data scientists, we have to use different packages for different algorithms and applications. I am sure some struck you as better than others, probably for various reasons. Reflect on why you thought some packages' documentation was better than others. That will help you know what to avoid when writing your own documentation.

Ask for Feedback, Reread and Revise

One great tool to produce better documentation is to ask for feedback from others. This can help you know what the users need/ want to be more precise, what is missing, and how your documentation can improve overall.

Final Thoughts

Nowadays, more than writing robust code is required; to prove your capabilities and how well you're familiar with the project and the field, you will need to provide well-written documentation and highlight how your code work and how it can be used.

Unfortunately, most of us would rather spend more time writing actual code than working on the documentation. In this article, we went through some steps that can make the process of writing code documentation easier and help you produce better-quality documentation.
 
 
Sara Metwalli is a Ph.D. candidate at Keio University researching ways to test and debug quantum circuits. I am an IBM research intern and Qiskit advocate helping build a more quantum future. I am also a writer on Medium, Built-in, She Can Code, and KDN writing articles about programming, data science, and tech topics. I am also a lead in the Woman Who Code Python international chapter, a train enthusiast, a traveler, and a photography lover.