System documentation to support outsourcing: the Case of the Missing Specs

A fast-growing supplier of e-publishing services found themselves increasingly outsourcing programming work to subcontractors, often located abroad. The sooner such subcontractors understand what has already been produced and what is expected of them, the better. Valuable time was being lost defining these issues. This not only cost money, it also meant that our client could not respond to requests from their own customers as rapidly as they would have liked.

What was achieved

Subcontractors now receive not just a description of requirements, but also a document that exactly describes the current state of the system that they are asked to work on. An updated version of this document is part of the deliverables. Thus, it is always immediately clear what has been coded, why and how. Subcontracting is faster and more reliable. New client requirements can be assessed, quoted for and implemented in much less time.

What it took

Based on national and international standards the structure for the systems documentation was determined. We spent one day with our customer defining the issue, the underlying requirements and any other considerations. We then studied their existing technical documentation and identified the bits that were missing. After the existing documentation was re-framed to fit the new structure, we turned that into a provisional Word template which was used by our customer's own staff to fill in the blanks. Finally, the structure was fine-tuned and the Word template finalized so that it could be used by third parties.