The Art of Writing Documentation

By Marty Jacobs

doc


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 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 your code is almost always a really good idea. If you don’t have the time to comment 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 readible and may take some time to decipher. But if the developer who took the time writing it… simply added in this single comment below…

//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 decipher it, OR
  2. We can continue coding/working to expand the solution.

Reference guides & API documentation

For reference documentation, the #1 rule here is Completeness. There is no further a frustration than a piece of information being left out of the docs. A good practice to validating your reference guides is actually proofing them. Checking them for completeness by testing edge cases and finding holes, afterwards correcting them.

APIs are everywhere, private or public. In your development career you might be required to write the documentation for an API. It is particularly important that API functions are properly documented and understood. This saves development time and testing, especially if the functions are ambiguous. There should be no confusing what a function actually does. You could go a further step and suggest why you would use the function.

SOPs (Standard Operating Procedures)

Standard Operating Procedures are used inside organisations 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 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.

Summing up

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. If you’re interested in improving your writing capability, I have included in my book here techniques to improve your writing skills. Hope you enjoyed the article! Thanks for reading.