The best documentation creates an organic system of knowledge.
Every project begins with some kind of documentation. The best projects begin with a full set of specifications. Those must include the user manuals. The user manuals define the goal. If you do not know where you are going, you never will arrive. Most often, technical specifications alone – perhaps only a statement of work – guide programmers who work intuitively. At the end of the process, they call in a technical writer to document their work. At that point, it is too late. Documenting “as built” work is like drawing blueprints for a house – or a neighborhood – after carpenters have been working as they pleased to do the best job they know how according to their own best judgment. We can hope that they knew their crafts and got along well.
On the positive side, the entire body of documents that we will see soon constitutes a inventory that can be a structured knowledge base, a single source for the consistent presentation not only of design specifications, but also for quality assurance and testing scripts, marketing content, sales materials, and training materials, for your own staff as well as for your customers and for their customers.