Posted on May 28, 2015
Unlike writing code (which is what developers signed up to do), documentation (which we didn’t) has to and should be easily digested by everyone. Technically, we have to translate a machine language (code) into a language that is understandable to humans, which is tougher than it sounds.
Although it can be a real burdensome, writing the documentation is important and will deliver advantages for your users, your colleagues, and especially yourself.
Good Documentation Helps Users
Documentation helps the reader understand how a code works, obviously. But many developers make the mistake of assuming that the users of the software will be proficient. Hence, the documentation may be thin material, skipping a lot of the essentials it should have contained from the beginning. If you are savvy in the language, you can figure things out on your own initiative; if you are not, then you are lost.
Documentation intended for users usually consists of practical use or the “how-to”. The rule of thumb when creating documentation for general users is that it should be clear-cut. Using human-friendly words is preferable to technical terms or jargon. Real use examples will also be greatly appreciated.
A good layout design would also really help users scan through each section of the documentation without eye-strain. A few good examples are documentation for Bootstrap and WordPress‘ “First Steps With WordPress”.
It Helps Other Developers Too
Each developer will have their own coding style. But, when it comes to working in a team, we will often have to share codes with the other team mates. So it is essential to have a consensus on a standard to keep everyone on the same page. A properly written documentation would be the reference the team needs
But unlike end-user documentation, this documentation typically describes technical procedures like code-naming convention, showing how particular pages should be constructed, and how the API works along with the code examples. Often we would also have to write the documentation inline with the code (known as the comments) to describe what the code is doing.
In addition, in the case where you have new members joining your team later, this documentation could be a time effective way to train them, so you don’t have to give them a 1-on-1 run down on the code.
Strangely It Also Helps The Coder
The funny thing about coding is that sometimes even the developers themselves do not comprehend the code that they have written. This is particularly true in cases where the codes have been left untouched for months or even years.
By documenting your codes, you will be able to get to the bottom of your codes quickly and without frustration, saving you a lot of your time that can be spent on getting the changes in.
What Makes For Good Documentation?
There are several factors that to build a good piece of documentation.
1. Never Assume
Don’t assume that your users know what you know as well as what they want to know. It is always better to start from the very beginning regardless of the users’ proficiency level.
The bottom line is the documentation is written with the thought process of a user, not a developer. Approaching your own documentation this way will give you a better perspective in organizing your own piece.
2. Follow The Standard
In adding documentation that goes inline with the code, use the standard expected of the language. It is always a good idea to describe each function, the variables, as well as the value returned by the function. Here is an example of good inline documentation for PHP.
· CSS: CSSDoc
If you are using SublimeText we would suggest to install DocBlockr that will cleverly pre-populate your code with inline documentation
3. Graphical elements
Use graphical elements, they speak better than text. These media come in useful, particularly if you build software with graphical interface. You can add pointing elements like arrows, circle, or anything that may help users to figure out where to go to accomplish the steps, without guesswork.
You may consider wrapping a few things in the documentation within bulleted lists and tables as this makes longer content easier to scan and read for users.
Add a table of content and split the documentation in easily digestible sections, yet keeping each section relevant with what comes next. Keep it short and straight forward. Below is an example of nicely organized documentation in Facebook. The table of contents takes us where we want to jump to in a click.
5. Revise and Update
Lastly, review the documentation for mistakes and revise when necessary or and whenever there are significant changes to the product, software, or library. Your documentation would be of no use to anyone if not regularly updated alongside your product.
*http://www.hongkiat.com/blog/why-documentation-essential/ by Thoriq Firdaus