Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Section
titleStructure

To reduce the distraction for the reader, the author needs to present the information in way expected by the reader. This expectation is expressed by a number of aspects of documentation.

Section
titleCommon Macro Structure

A document of a given type should have the same structure independent on when or by whom it has been written.

Navigation options should be the same throughout the documentation.

See Use Templates.

Section
titleCommon Layout

Readers expect a common structure for documents and the documentation. A requirement documents should have the same structure independent on when or by whom it has been written. Navigation options should be the same throughout the documentation.

See Standard Layout.

Section
titleSame Language

The documents should be written in the same tone and language complexity. Readers have an easier job to digest the information in the documentation if the individualism of different authors does not shine through.

A clear language also reduces ambiguity which may lead to false understanding.

See Employ a Style Guide and Maintain a Glossary.

Section
titleDiagramsCommon Diagram Style

Diagrams should use a notation that is properly explained. Every element within a diagram should be explained. The elements of a diagram should be limited to what is essential to a given context (7+/-2 elements per diagram as a crude rule of thumb).

Section
titleExpected Detail

The level of details revealed in a document should match the expectation of the audience. Therefore it should be made clear by the author what the level of experience the audience should have, which roles they are in and which level of details is provided. It is also important to state the purpose of the document to the audience.

With this information the audience will have the right expectation for the document.

...