The Art Of Software Development (part 4): Delivering Quality - The Write Stuff (
Page 6 of 7 )
Simultaneous to testing is documentation, the activity of providing your
customer with written information on the software being developed. This
is not the most interesting of activities; however, it has tremendous
value to the customer and should therefore be considered an important
deliverable of the project.
Documentation comes in many flavours; when dealing with software, one of
the most common ones is the user manual, which demonstrates to customers
how the software may be used. This manual is critical in training your
customers on correct operation of the software, and - if clearly written
- can substantially reduce the time you spend on post-release support.
This user manual typically contains detailed information on the features
and goodies built into the application, and focuses on demonstrating how
to accomplish common tasks within the application; it also provides
detailed examples, complete with screenshots and sample data, and
explains the significance of the various status and error messages
displayed by the application. This material is written for, and targeted
towards, the user profile and skill set defined in the earlier phases of
the project.
In addition to a user manual, some customers also require a developer's
guide, which contains technical information on the software that has
been developed. This guide is usually targeted at more technical users,
such as system administrators or developers, and should therefore
contain as much information as possible on the application design, data
processing and internal logic flow, performance and security
considerations, data storage constraints, interprocess communication,
exception handling, resource management et al. It should also contain
high-level architectural diagrams of the system design (including models
of component relationships) and a detailed function reference, or API,
to all the functions used within the application.
Some projects or customers may additionally demand detailed design
documents, architectural flowcharts, API specifications, and technical
software specifications; you should try and provide this information if
possible.
Since documentation is usually customized to each project, expect to go
through a couple of reviews and revisions until it fully satisfies your
customer. Typically, documentation is developed near the end of the
project; however, depending on your workflow, you may even have a writer
working on it through the different phases of the project, revising it
as per customer feedback at different points, and delivering the final
version simultaneous to the software release.
It should be clearly understood that documentation is an art in itself -
it's unfair to both your customer and your team to treat it as a
second-tier deliverable and not assign it adequate attention or
resources. Remember that your customer is paying for well-written
documentation, and that he or she expects to use it extensively, either
for internal user training or for future development of the software; it
therefore constitutes an important deliverable of the contract you have
undertaken.
If you can afford it, always consider hiring a professional technical
writer to develop documentation for your project - the returns, both in
terms of customer satisfaction and lower stress levels, will be well
worth the additional cost.
/ 4 
