Audience and Purpose

Understanding your audience is important in any writing, but particularly so in communicating a system design, since you're likely to have several types of readers with different requirements.

You need to consider what you and your readers are trying to achieve. Your clients primarily need to confirm that you've understood their requirements and secondarily want to gain some assurance that the system will achieve their goals. Your clients don't need (or want) to understand the details of how the system is to be implemented. But if the document is going to be used as the basis for development, the development team needs to see exactly those gory details that will make the client's eyes cross.

Sometimes the best solution is to prepare several documents: one for the client and a different one for the development team. This is a particularly good approach if you're using an iterative development model, since it closely matches the model. In these situations, I usually write multiple documents:

• A Requirements Specification, aimed primarily at the client, that documents my understanding of the system in (relatively) non-technical terms.

• An Architectural Specification, read by both the client and the development team but aimed primarily at the latter, that details the interactions and dependencies between components.

• A separate Technical Specification for each component, for use by the development team.

For simpler systems, a single document will usually suffice. Just be sure that you've considered the needs of each of your audiences and provided the information required by each in a format that they can easily understand.