Image of The art of writing software documentation (Updated 2019)

ADVERTISEMENT

Table of Contents

Introduction

Software projects today don't place emphasis on documentation. This might be due to project deadlines or documentation being very low on the priority list. It might be cultural, following a methodology such as Agile, where there is less emphasis on documentation writing and more on delivering value to the customer. First of all, documentation is an art, particularly under the pressure of time. It is very clear to me that documenting complex code, keeping the end-user front of mind, and focusing on the message are necessities in writing clean documentation.

Write for the end-user

The best documentation always has the end-user top of mind. This statement holds true in all cases, as there is no point in writing documentation if no one even understands what you are writing. You're better off not writing at all!

So that is why the #1 rule is - Write for the end-user.

When writing documentation it is helpful to ask yourself, "Will someone who has no knowledge of the subject understand exactly what I'm saying?" If you believe the answer is yes, then you're likely to be on a good path to writing some solid documentation. Often times this means cutting out unnecessary detail and "dumbing it down", so it is easy for people to follow and get a good grasp of the concept.

Code commenting

Everyone codes differently. Your style might be very different from another developer, so commenting on your code is almost always a really good idea. If you don't have the time to comment on your whole code base, that's fine, then why not just focus on the complex routines instead? Complex code takes time to understand.

Take below for example...

int v,i,j,k,l,s,a[99]; main() {
for(scanf("%d",&s);*a-s;v=a[j*=v]-a[i],k=i<s,j+=(v=j<s&&(!k&&!!printf(2+"\n\n%c"-(!l<<!j)," #Q"[l^v?(l^j)&1:2])&&++l||a[i]<s&&v&&v-i+j&&v+i-j))&&!(l%=s),v||(i==j?a[i+=k]=0:++a[i])>=s*k&&++a[--i]);
}

If you saw that... What would you do? It is extremely complicated C code, although very succinct, it is hardly readable and may take some time to decipher. But if the developer who took the time writing it... simply added in this single comment below...

int v,i,j,k,l,s,a[99];

main() {

    // Prints the N-Queens solution to the console

    for(scanf("%d",&s);*a-s;v=a[j*=v]-a[i],k=i<s,j+=(v=j<s&&(!k&&!!printf(2+"\n\n%c"-(!l<<!j)," #Q"[l^v?(l^j)&1:2])&&++l||a[i]<s&&v&&v-i+j&&v+i-j))&&!(l%=s),v||(i==j?a[i+=k]=0:++a[i])>=s*k&&++a[--i]);

}

Ahh now that makes sense, we know exactly what it does. The code is solving a specific problem. By adding that one extra line, we now have some context into why they authored the code in the first place. We know the code is solving the N-Queens problem and we know it prints the solution to the console. So we have these two options,

  1. We can choose to decipher it, OR
  2. We can continue coding/working to expand the solution.

Reference guides & API documentation

Standard Operating Procedures are used inside organizations to document complex routine operations (Either technical or non-technical). Here, more than ever is a good time to keep the end-user in mind! If they get confused half-way through the process, they could get it wrong. A good habit to adopt is before you sit down to write the SOP, put yourself in a new starter's shoes. Imagine you have no understanding of how to do the procedure.

It will help you write - by having perspective.

Cross-checking is another recommended way to improve your documentation. Send it to a colleague and request for feedback. They haven't seen the document before so there is a good chance that they will be able to see the holes that you don't.

Tutorials

Writing programming tutorials is for teaching other developers. The number #1 rule here is to focus on Learning and Engagement. When writing programming tutorials, you want the content to be engaging so the end-user "does not fall asleep". Some good tips here are including rhetoric, pictures, memes, jokes to add some life to the content. This way the content is not dry.

People learn in different ways, some are theoretical and others learn-by-doing, so another effective method for tutorials is interactive tutorials. There are several learning providers that offer "virtual labs" that you can run code and see the results. This is a really effective way of teaching developers complex topics.

Conclusion

There is not always enough time for documentation. Keeping the end-user in mind helps you to write successful documentation, even if it is quite lean. It is an excellent practice to undertake as it can help your project advance in the future, and you can leave knowing that people understand your code and understand what you are writing. Thanks for reading, I hope you found this article helpful and good luck with your documentation!

Final Notes