Requirements Modelling and Specification for Service Oriented Architecture

7.8. Documenting the Specification

A specification is a description of a desired machine. In the context of SOA it is the description of a desired set of service interfaces and the specification of the components that will implement them. It says what the users may expect and what they must do to obtain correctly functioning services. It should also make reference to any business process models that provide the context for the specification, or which the services may be choreographed to implement.

Huge wordy specifications are to be avoided; the general principle is: only write documentation that will be used. For example, if you will be the designer as well as the analyst, you can defer some of the specification until you document the design. Also avoid comprehensive wall-sized diagrams of the type model. It is far better to fragment the diagrams and organize them around process or service descriptions.

Narrative descriptions of processes process and services are most useful, in our experience. They should be illustrated with relevant fragment of the type model and supported by a glossary of types. Relevant business rules should be included.

The documentation should also include deliverables inherited from the business process analysis: business objectives with measures and priorities, cross reference tables for conversations/processes and objectives and the process models themselves.

Above all, keep it simple and keep it as concise and as short as possible - but no shorter! ...