Summary: This article written by Kumar Raman 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.
About the Author- 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.
_________________________________________________
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 practices. Often, a proposal fails to convert to a project because the proposal documentation lacks concise and expressive language, professional organization and polish. It may not be their inability to deliver, but their inability to express their capability.
For many, documentation is only about creating user manuals and online help, and even that documentation lacks an established process. When a project nears completion, a writer is called upon to document it. Someone sits with the technical writer and quickly runs through the application, telling the technical writer to prepare a user manual and to “please call on me if you have any questions…” The technical writer does their best to prepare a manual for the application. Then come the calls for more training or help over the phone, and half of the support staff will be answering queries on the user manual itself. Think how much time would have been saved if the documentation had been considered an important part of the process from the beginning.
Doing it is important!
It’s not that we don’t know how to do the documentation right. We just don’t think it’s important. The simplest thing one can do is to involve documentation people from project initiation and let them understand the project dynamics, technology, domain, and objective. We need to make sure the person who does the documentation—whether internal or external—understands the document audience well, and the purpose and objectives of creating the document. Once this is done, the documentation will be organized and articulated in a way that makes sense to the readers. The idea behind this is to take a proactive approach toward documentation. We will surely be better off planning our project documentation and executing it when the writers know the purpose and stay involved throughout the lifecycle.
To set our documentation standards in place, we need to integrate our software processes with our project documentation requirements; specifically, the various documents and records we create for our quality conformance purposes should adhere to set document standards. There might be the understanding that “we already have templates that we follow.” But I am not talking about the process we follow for certification’s sake (e.g., ISO or CMM). I am talking about synchronizing our real quality assurance with our documentation standards and other processes. Hence, it is very important that both our QA and documentation processes go hand-in-hand and that both departments work in synchrony. It actually has to be a synchrony triad—the processes defined by QA, followed by the technical people, and documented as per the standards.
Remember that change happens slowly. This morning, I spoke to our team of project owners and told them it is important to follow whatever standard templates and styles we publish. As I was enjoying my cup of coffee with a sense of satisfaction thinking about the morning session, I received a call from one of the project owners. He congratulated me on all my endeavours to bring order to the chaotic environment, and then he came to the point: “Kumar, I have a document to be reviewed. I wish I had time to format it in line with the dot template you sent me the other day; but I think you will appreciate that I have an important design review to attend. Can I send you the document and ask that one of your technical writers format it according to our style before it is reviewed?” I hung up the phone with a very hesitant “Yes.” Old habits die hard, but if we are persistent and patient, our efforts will pay off, and others will appreciate the importance of documentation to quality assurance.
No comments:
Post a Comment