Documentation seems to be the bain of every developer’s existence. We spend hours figuring out the solution to a problem, and then are expected to regurgitate that information all over again in a palatable format. This is difficult for a couple of reasons:

It is always boring to reiterate something you already made once.

We all remember those essays in school where you type out 3 or 4 pages, then accidentally spaz out on the keyboard and delete it all. It is always so much harder to produce the same quality of output on the second go-round. Luckily, OneDrive and Cloud auto-saves prevent this from being an issue now.

Sometimes a task is very complicated and the path to the solution was not all that clear.

Often times we are required to travel a very circuitous path to arrive at our solutions to a problem. When this is the case, it can be difficult to remember how we got to the destination (although that makes it all the more important to follow our points in the article).

Why it is Important

Despite the possible annoyance it poses, documentation is extremely important. You may be thinking “why do I care if another developer after me can reproduce my steps?”. Well, there are several reasons you would want to have a record of your work:

Less time answering their questions yourself.

Instead of repeatedly typing out the same response to a question of “How does this work” or “How do I use this”, you can have a document that explains everything clear as day. You shoot them this document and no longer have to repeat yourself.

This makes you look good.

Your boss will be impressed by your organization, and you can highlight the important features and impressive work you have done.

Now you have something to refer to for yourself.

If you developed the tool a long time ago, you may not remember all the minutiae that you would have been very comfortable with during the developments. What happens when the customer comes back to you and needs something tweaked or finds a bug? With proper documentation, you will be able to quickly refresh yourself and get back up to speed.

Documentation Principles

Here are some helpful tips for when you do document your work.

Consistency

Always be writing the documentation. Do not wait till the end. You will dread all of the work and it will take you a much longer time to recap and remember all you did.

Be Clear

Be sure to have a precise way with your words. Try to think “if I knew nothing about this code, does my document make sense?”

Provide Examples and Images

Pictures and code snippets always help the user understand and implement a solution more easily. API’s and documentation with real usage examples are almost always superior.

Conclusion

With this knowledge and reminder, I hope you can provide great documentation on all your future work. Anyone working with your code will thank you!