HomePractices Page 6 - The Art Of Software Development (part 4): Delivering Quality
The Write Stuff - Practices
Just writing code isn't enough - you also need to test itthoroughly before you release it to a customer. This article discussesthe testing phase of the software development cycle, providing you withan overview of test cases and testing processes, together with adiscussion of how to go about documenting your software in a clear andconcise user manual.
Simultaneous to testing is documentation, the activity of providing yourcustomer with written information on the software being developed. Thisis not the most interesting of activities; however, it has tremendousvalue to the customer and should therefore be considered an importantdeliverable of the project.
Documentation comes in many flavours; when dealing with software, one ofthe most common ones is the user manual, which demonstrates to customershow the software may be used. This manual is critical in training yourcustomers 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 featuresand goodies built into the application, and focuses on demonstrating howto accomplish common tasks within the application; it also providesdetailed examples, complete with screenshots and sample data, andexplains the significance of the various status and error messagesdisplayed by the application. This material is written for, and targetedtowards, the user profile and skill set defined in the earlier phases ofthe project.
In addition to a user manual, some customers also require a developer'sguide, which contains technical information on the software that hasbeen developed. This guide is usually targeted at more technical users,such as system administrators or developers, and should thereforecontain as much information as possible on the application design, dataprocessing and internal logic flow, performance and securityconsiderations, data storage constraints, interprocess communication,exception handling, resource management et al. It should also containhigh-level architectural diagrams of the system design (including modelsof 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 designdocuments, architectural flowcharts, API specifications, and technicalsoftware specifications; you should try and provide this information ifpossible.
Since documentation is usually customized to each project, expect to gothrough a couple of reviews and revisions until it fully satisfies yourcustomer. Typically, documentation is developed near the end of theproject; however, depending on your workflow, you may even have a writerworking on it through the different phases of the project, revising itas per customer feedback at different points, and delivering the finalversion 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 asecond-tier deliverable and not assign it adequate attention orresources. Remember that your customer is paying for well-writtendocumentation, and that he or she expects to use it extensively, eitherfor internal user training or for future development of the software; ittherefore constitutes an important deliverable of the contract you haveundertaken.
If you can afford it, always consider hiring a professional technicalwriter to develop documentation for your project - the returns, both interms of customer satisfaction and lower stress levels, will be wellworth the additional cost.
Practices 
/ 4 
