Listen to Your Favourite Programming Podcasts and Books on Audible - Here is a Free Trial - Click Here - Offer Limited Time Only
The Art of Writing Software Documentation (Updated 2019)

# The Art of Writing Software Documentation (Updated 2019)

## Marty Jacobs · Apr 28, 2019 00:00 · 865 words · 5 minute read

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 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 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 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.