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.

To understand who's going to be reading the document, and therefore what you should include, you need to consider what you and your readers are trying to achieve. Your clients need to confirm that you've understood their requirements and gain some assurance that the system will achieve their goals. They don't need (or want) to understand the details of how the system is to be implemented. If the document is going to be used as the basis for development, however, the development team needs exactly those 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) nontechnical 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 they can easily understand.