The Power of Documentation and Commenting the code

I have spent most of my career as a programmer. Most of the time i have been a stand alone programmer. I have existed in organizations where documentation is always needed before a code can be written. where before you change a small bug in the program, you need to submit a change request document. By that time it looked like a waste of time, because most programmers are not fond of writting documentation, infect we rarely use Microsoft word. In this article i will share my experience and the danger of not documenting your work.

Introduction

I have spent most of my career as a programmer. Most of the time i have been a stand alone programmer. I have existed in organizations where documentation is always needed before a code can be written. where before you change a small bug in the program, you need to submit a change request document.  By that time it looked like a waste of time, because most programmers are not fond of writting documentation, infect we rarely use Microsoft word. In this article i will share my experience and the danger of not documenting your work.

What can Documentation do For you

Good Question what can Documentation do for you ? Documentation can do a lot of things. Let me give you some of the things that documentation can do for you and i will explain later what i mean. 

1. Documentation can save you from getting fired.
2. Documentation can save you time you spend to find a Bug
3. Documentation will save your company money
4. Documentation can get you started very quickly in a new job

Let us discuss these four points. 

Documentation can save you from getting 

Documentation can save you from getting fired , means that it can protect you. Remember the standard procedure in software development world. First you need to identify the problem and write a proposal document that explains what you are about to do for them , and they will look at it and agree or disagree or request you to change something from the document. After they are happy with the proposal , You will draw up a functional specification that will explain clearly technically how the application is going to work and the technologies that will be used to develop that application. Again that document must be submitted to be approved. This means that tomorrow when they say they did not request the application to be like that you will be safe because they have signed and that means they have agreed that the application will be done that way. This will save your job as a developer , because you designed based on what is written in the Functional Specification. Paragraph Title 2Paragraph contents goes here 

Documentation can save you time you spend to find a Bug

Documentation can save you time you spend to find a Bug, means that it can save you time you spend to find a bug. A Functionality that is not documented is not easy to debug. Because you need to first know what it is doing and find a bug in that. How can a new developer find a bug in a functionality that is not documented ? Let us say a Developer left without documenting a functionality and no one even bothered to write documentation for a functionality. This will lead to a waste of unnecessary time that will be spent to find a bug and at the same time many questions will be ask , and sometimes there will be no accurate answers and this will mean a developer needs to sit down with the users and understands exactly what was the functionality doing and that is time and after the developer understand the functionality he will need to look at how the previous developer designed the functionality and after that find the bug and fix it and test it. What i just wrote might even lead to weeks and a months of time wasted because no one invested his time in writting documentation for the system. 

Documentation will save your company money

Documentation can save your company money, means that if everything is documented and well organized your company will save a lot money. Some of the programmers are paid hourly. If you look at the previous point i have made complements this point. In some companies programmers are paid for wasting time. It is like an Infinite loop. This is because there is lack of documentation. Project that were completed in the past designed with old languages like VB6 cant be upgraded because of lack of documentation and if an attempt to convert those projects to C# or VB.net, the Projects drags to a period of a year or two years, because programmers will be converting to a new technology as the same time figuring what does the functionality is supposed to do and on the other hand having technology challenges because for some reason , the way things were done in the past language is done differently with a new language and that might propose for a new design way to deal with a problem. These kind of things leads our companies to lose money and retrenchments might follow because the department cannot afford to pay the salary of a programmer. You can make a difference and go the documentation route, this will not save your company money but it will save your friend who is your colleague from being retrenched.

Documentation can get you started very quickly in a new job

Documentation can get you started very quickly in a new job. Just image when you start a new job and they tell you that they have no documentation for their applications and you will have to learn while you are going. They might even tell you that you will come across problem and they will make you understand the system. believe me there are big companies that do that.  I remember one time i went a certain company and they told me that they don't have any sort of documentation, you just being told to add a functionality because there is no time, there are a lot of clients on demand. I thought to myself if i want to kill my career i will follow that route. My point is that when you apply for a new job, find out about their documentation processes or let they explain their development processes and if they don't mention anything about documentation , ask them and ask them who will do the documentation. From there you can know what kind of company are you letting yourself into. Because not all development work is googlable or you can ask on the forum, some are so complicated and the answers can only come from the company itself and if they don't have documentation its chaos. 

Where to Start

One might start asking, where do i start practicing this. First there are templates on the web that can guide you to write documentations. I have compiled some links that will help you. 

http://www.stcsig.org/mgt/docs/uncspectempl.pdf

http://www.techtransform.com/process/PMTech/FUNCTEMP.pdf

http://www.bredemeyer.com/pdf_files/functreq.pdf

and for Change requirement Documents you can get the templates here 

Change Document Template 1

Change Document Template 2

Change Document Template 3

Remember that the Change document will be used as a permission to change the Application. This needs to be approved so that it can save you and your company and possibly your friend as i mentioned in the above points.

Conclusion

Application without documentation is evil to your career. If you don't know when to start writting your documentation you can get templates as i have shown you. That will give you an idea on how to do it.  Documentation is the way to go. 

Thank you for Posting at DotnetFunda

Vuyiswa Maseko 

转自：http://www.dotnetfunda.com/articles/article468-the-power-of-documentation-and-commenting-the-code.aspx