Home arrow Practices arrow 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.

  1. The Art Of Software Development (part 4): Delivering Quality
  2. Code To Zero
  3. Casing The Joint
  4. A Man With A Plan
  5. Bug-bustin'
  6. The Write Stuff
  7. Endgame
By: icarus, (c) Melonfire
Rating: starstarstarstarstar / 4
September 24, 2002

print this article


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.

>>> More Practices Articles          >>> More By icarus, (c) Melonfire

blog comments powered by Disqus
escort Bursa Bursa escort Antalya eskort


- Calculating Development Project Costs
- More Techniques for Finding Things
- Finding Things
- Finishing the System`s Outlines
- The System in So Many Words
- Basic Data Types and Calculations
- What`s the Address? Pointers
- Design with ArgoUML
- Pragmatic Guidelines: Diagrams That Work
- Five-Step UML: OOAD for Short Attention Span...
- Five-Step UML: OOAD for Short Attention Span...
- Introducing UML: Object-Oriented Analysis an...
- Class and Object Diagrams
- Class Relationships
- Classes

Developer Shed Affiliates


Dev Shed Tutorial Topics: