Documentation and QA

[article]
Two Sides of a Coin
Summary:

This article is all about wearing your documentation cap with pride as you do your other technical and quality caps. Documentation is as important as any other aspect of a project, like analysis, design, coding, testing, etc. The problem is that we do not realize its importance. Once we do, we can deliver products with a higher level of perfection. This has to be understood, appreciated, and infused into our system.

Before joining my current organization, I had never heard people talking about documentation as a separate area worthy of much attention. The general opinion was that anybody who was free could do it-whether creating plans (e.g., the QA plan, test plan, or SCM plan), templates for reviews, status reports, time sheets, or the user manual. Having special technical writers was considered a good idea, but a luxury.

An Eye-Opener
During the interview for my current job, I talked at length about everything from software process to management and metrics collection. I did not stress documentation, even though it is my core area. I felt that talking about documentation would sound like I had no other skills, because I considered it the least marketable skill. Even when my interviewer asked about my documentation work and experience, and then started to tell me why he thought that documentation can make or break a project, I did not think he took it seriously. Nevertheless, I joined the company to head the documentation area.

The day I joined, our managing director sent a message to everybody saying that no documents-internal or external-would leave the company without my review. He gave an example of how a well-written, thirty-page document fetched us a million-dollar project. "We knew we could deliver if we got the project, and the bridge between us and the project was our proposal. We understood this and worked hard on this. We took extra efforts to express ourselves fully with a professional and holistic appeal and that paid off. We got the project," he told me later. This was a first for me: I saw someone at the top who felt documentation was an important part of quality assurance!

Documentation? What's That?
We have all read a lot about technology, quality, certification, testing, automation tools, and processes. But how many of us have seen articles on documentation? There are few, not because documentation is not important, but because we have not yet realized its potential. There is still a perception in some that documentation is less significant than analysis, design, or coding.

But we should appreciate that fact that documentation projects have levels of maturity, just like the software process. The book Managing Your Documentation Projects by Joann T. Hackos is one of the best books on how project documentation can be standardized and how standardized project documentation improves a project's quality. When compared to those levels, many software companies would not qualify as low-level documentation organizations, having only ad hoc documentation practices and no documentation experts. Most companies do not give a fraction of the importance to the documentation process that they give to their software development processes.

The fact is, careful documentation can save an organization time and money. Unless you are able to produce a document that makes the user comfortable and agreeable, no matter how superior your product might be, people will refuse to accept it. In my opinion, Microsoft's MSDN is one of the finest product guides ever produced. Given the scale of products they offer, they would be lost without an established documentation standard. Today, even with their massive size, Microsoft launches products with professional documentation. Some may dismiss this by saying they have the resources that others lack. But did they always have the resources? At some point they placed a priority on documentation. That is one of the reasons that all their products are self-contained and successful. That saves millions of dollars, not only for Microsoft, but also for all kinds of businesses today.

Small companies also can gain by developing good documentation staff and

About the author

Kumar Raman's picture Kumar Raman

Kumar Raman was a business journalist with a leading national economic daily in India. He has varied newspaper experience, picking up knowledge in domains such as finance, banking, insurance, stock markets, etc. In information technology, he has worked on both Microsoft and Java platforms, playing a variety of roles from analyst programmer to quality facilitator to project leader. He now heads the documentation for Arkin Systems, a leading producer of industrial grade software and one of the leading private software export firms in India. Kumar Raman works with Arkin Systems Pvt Ltd (Chennai, India), as Documentation Lead. He can be reached at kumarr@arkinsys.com.

StickyMinds is one of the growing communities of the TechWell network.

Featuring fresh, insightful stories, TechWell.com is the place to go for what is happening in software development and delivery.  Join the conversation now!

Upcoming Events

Apr 29
Apr 29
May 04
Jun 01