I realized the importance of documentation many years ago when I joined an organization to head its IT function. The previous IT head had left the organization a couple of months ago. The managing director called me over and voiced his expectation. He told me that all ground work had been done for ordering new set of servers and application packages and that I should act upon it soon. I promised to take a look at the situation and revert with plans.
However, when I sat in my department and rummaged through papers, I could not find much except notes on discussions with the vendor and details of configuration. For instance, there was no document showing an IT plan, applications to be developed / bought, functional areas to be covered, priority of tasks and justification for the equipment and software to be bought. When I went back to the boss expressing my helplessness in the absence of documentation, he was visibly annoyed and refused to discuss further. I then spent the next three months drawing out fresh plans and submitted them for approval.
Having learnt the lesson, I made it a point to always submit a handing over report to the management whenever I left any organization, which carried details on the IT set up, current status on various tasks, pending work, and the matters that would need attention in the following six months.
Consequences of poor documentation
Proper documentation is essential at every stage of our working and it doesn’t have to wait for a specific occasion. Documentation is simply a habit and a discipline and contrary to what many think, it does not require great effort. Good practices speak of creating documentation alongside and not to wait for the entire work to be over. I have faced several embarrassing situations due to lack of documentation. In one case, my assistant misplaced documents relating to approvals and vendor negotiation thus attracting auditor’s comments for loss of control.
Failure to record discussions and agreement with users has often lead to damning arguments during implementation stages. Not documenting system specs has got many of us in trouble. Absence of software specifications or incomplete specs makes many a developer code again rather than trying to rectify an earlier program. Lack of proper recording of approvals for user rights in the user profile can be a serious lapse and may cede ground for frauds to be committed.
What constitutes documentation
Documentation involves creating documents to record details / specification / events or storing and preserving documents that are relevant. They are important for the purposes of recording details of various activities, for retaining as evidence, for documenting policies & rules, for exercising control, preserving for posterity or as instruction for work to be done. Documentation can be on any medium including paper, on disks, DVDs, or on common repositories accessible on the net.
Types of documentation
I would classify documents in the following few categories:
General: Information systems plan, IT strategy, yearly budget, and the spends against the budgets, proposals for projects and their approvals, minutes of important meetings, periodic reports to management, etc.
Commercial: Request for Proposal (RFP), Record of talks / negotiation with vendors, PO copies, correspondence, etc.
Project documents: Requirements, statement of work, scope of work (SOW), software design and functional specification, system design and functional specifications, change management, error and enhancement tracking, user test and acceptance (UTA), and end-user manuals.
Others: List of IT assets, network diagram, security policy and other policies, disaster recovery policies, and action steps, etc.
When to start
I am told by many, that Indians are poor in documentation because of the legacy of the old Vedic period when thousands of lines of verses were carried through generations just by word of mouth. I do not however believe on that theory and strongly suggest that it is matter of habit. All IT service companies and consulting houses are immaculate in their documentation as it is a requirement dictated by the contract of services they have with their customers. It is however in the end-user companies that we face this problem.
The question, when to start: well, it is ‘now’. It doesn’t matter where we begin but we have to make a start and slowly build up our repository and should not be found wanting when any crisis strikes.