Documentation

Our team currently has a task to update our design documentation based on the changes we made when migrating to a new tool set. The amount of documentation change is small. Our goal was to ensure that functionality remained unchanged during our tools upgrade. We only had to modify one small part of report invocation. Unfortunately we found out that nobody knew the process to perform the update.

Part of the confusion stems from the fact that the software maintenance is being performed by a new company that recently won the contract. In addition, the customer decided to become more involved with the documentation management. This just adds complexity to an already complicated task. Previously the development team used to make design changes in Rational Rose. We would use Rational SoDA to extract design information from Rose to produce the design document. But SoDA has some problems which we were unable to resolve. So the process changed to involve SoDA generation with some additional markups by hand. Things got hectic when the previous company that did maintenance was wrapping up their contract. The SoDA generation was dropped and a Microsoft Word document was edited exclusively to incorporate design changes.

Currently one individual in our client organization is tasked with managing the latest version of all documents. This includes our large design documents. One would think that development could go to this individual to get the latest version of the design doc for update. But we have been cautioned that this individual sometimes gives out the wrong version of the document. Furthermore I do not think any of the procedures are documented. And if they are, the development team does not know about them. I sense a severe weakness in the maturity of the process here. This will most likely come out if we were to be audited.

I think somebody is working on these problems. This impacts the day to day work when a developer needs to document some design changes. In general, coders do not like to perform documentation tasks. So nobody is sweating this problem just yet. However we are embarking on the design for a number of new features requested by the client. Therefore things are about to get very hectic real quick in our documentation world. Good luck to us.