Benefits of Software Documentation - SDLC Best Practices

We all read different articles on documentation and methods, but how many of us know the important of documentation? No doubt there are few, Is it that documents are not important? No, but its’ because we have not yet realized importance of documents.

“Ink is better than the best memory” – Chinese proverb

“No matter how wonderful your library is and how intelligent its design, if you’re the only one who understands it, it doesn’t do any good” - Hemal Fofaria

It’s my experience, we own one product, which is having a bit confusing functionality. When I started working on that I asked for some help documents I got answer “No, we don’t have any documents”

The reason why documentation is important for developer is because if it was not written it was not done. Documentation provides a written account of activities as they happen. It is a place to go when time has passes and memory fails us. It is also a form of written proof that something was done or said. Documentation gives the ability to have another account of a situation and helps us have something to fall back on other than the word of one individual.

The importance of software documentation to software developers lies in the fact that software documentation contains information on the operations of the software system. This information makes it possible to reproduce the software or adapt it to maintenance. The type of information documented is usually worth millions to the software company. Such information could be lost if not documented as developers come and go.

Documentation is about professional communication related to product or service.

Even same thing is applicable for User manuals. Take an example of Microsoft, they launch every product with proper documents, even for Office 2007 we have such documents, which are very explanatory and easy to understand for any user. That’s one of the reasons that all their products are successful.

In small companies, we always heard “project rejects in proposal or kickoff phase” it’s just because proposal documentation lacks concise and expressive language, and to show the capability of the organization. It’s not that small companies can’t deliver good quality projects but it’s their inability to express their capability.

Fact is that, careful documentation can save an organization’s time, efforts and money. While going for any type of certification, why there is stress given on documentation, it’s just because it shows importance of client and processes to individual and organization. Unless you are able to produce document that is comfortable to user no matter how good your product is, no one is going to

“Lack of documentation is becoming a problem for acceptance” – Wietse Venema

The purpose of technical documentation is to:

1. It’s important for others to understand your code/functionality.
2. Gone are the days when one coded with the intention to just make the product work, now if 40% effort goes to the actual coding then the remaining must go on making it re-usable and well documented for future use.
3. Documentation offers immense support for maintenance.
4. Documentation is important for others to understand your communication in professional way.
5. Documentation is require to recognized what we coded, if the code gets a bit older.
6. It helps explain the overall picture of what a piece of software does and how its various modules and components work together, it can also on demand show dependence’s, peoples responsibilities, and other useful team info.
7. Reduced maintenance times, with documentation to help, implementation new features and picking up unfamiliar code should be quicker
8. New recruits will be able to get up to speed quicker.
9. Clarify quality objective and methods
10. Ensure internal co-ordination in client work.
11. Create objective evidence of your quality management system’s performance

 The purpose of functional documentation is to:

1. Describe the use, operation, maintenance, or design of software or hardware through the use of manuals, listings, diagrams, and other hard- or soft-copy written and graphic materials.
2. Assign responsibilities and establish authority for business processes and practices (pertains mostly to policies and procedures).
3. Standardize business practices.
4. Reduce/eliminate fraud, waste, and abuse.
5. Comply with federal, state, and local regulations.
6. Comply with customer requirements.
7. Comply with contractual requirements.
8. Train new employees.
9. “Self-service”. So customers can use our services without contacting anyone on our end, which can be beneficial to both them and us.
10. Transparency. One of our “core values” is being open about what equipment we use, how we set the equipment up, how we bill, how we monitor, etc. etc.
11. Entice new customers—they see our docs and that hopefully answers their questions about our products and assures them that we are competent and know what we are doing. (And I like to think that having neat, grammatical, concise docs makes a difference here, even if doc style has nothing to do with our main abilities as a company.)

Software Documents always play an important role in Project development/testing phase. So always keep things documented whenever possible. Don’t rely on verbal communication. Be always on safe side. Documentation will not only save you but also help organization in long run saving thousands of dollars on training and more importantly on fixing issues caused due to lack of development and testing documents. Don’t document just to avoid finger pointing on you, but habit of documentation will certainly bring a systematic approach in your SDLC processes.

All software, from simple command line utilities to large scale corporate systems, needs documentation. It may be done either in the form of several text strings shown in a console window or in the form of thousands of web pages stored on the company portal in a distributed database. No matter how documentation is done, it must be done.

Nevertheless there are many situations when you have an application but there is no help file with it, and you have no time to write complete documentation yourself. At the same time you have no budget to hire a professional technical writer who can do this tedious work for you. It will represent companies can’t deliver good quality projects but it’s their inability to express their capability.One of the benefits of software system documentation is that we can preserve the history of the systems at different cycles and in turn facilitate the use of it by the users and maintainers. The latter are those who are in position to bring to-date documentation. Basically, the objective of documentation is to teach, those unfamiliar with the system, how it is structured, how it works. Additionally, software documentation facilitates interpretation of the system.  One of the biggest problems that many of us experience at some point is where you run into specific system design problems without having a guide.  It’s like going through a jungle without a map or compass. The result is significant loss of time and money many times. While software system documentation can be a tedious task, even more so when there is large scale, complex systems, someone has to do it.  Documentation of maintenance systems may have a significant cost, but if the investment is done correctly, it is worth it in the long run.

Point to ponder - Don’t go to jungle without a map or compass.

About Author:

Hemal Fofaria is a consultant in Systems Plus Pvt. Ltd. Within Systems Plus, he actively contributes to the areas of Technology and Information Security. He can be contacted at hemal.f@spluspl.com