- Created by Robert Reiner, last modified on 29. Apr 2017
Communicate in a way expected by the reader.
- Domain
- Type
- Principles
The readers' first concern is not to read, but to find and understand the information they seek.
How can authors support the reader to get the information of a document quickly and without distraction?
Structure
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.
Common 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.
Common 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.
Same 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.
Common 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).
Expected 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.
Advantages
- The reader finds and understands the information more quickly.
- The documentation is perceived by the readers to have a high quality.
- Authors may find it easier to create documents if some basics are already defined.
Disadvantages
- Having all rules upfront is a major investment. Agile teams typically define only a small number of rules and evolve their set of rules over time.
- Having a commonly used style requires resources, even if developed on-the-fly.
- Evolving rules over time typically requires to update already created documents.
- It takes discipline on the side of the authors to learn the rules and to apply it. It helps tremendously if team members have access to a wiki gardener or other expert on technical writing.
Related Practices
The following practices are related to this practice.
- Use Templates
- Define a basic structure for all artifacts of a given type. Readers will have an easier job on finding and learning about the information in your documentation.
- Employ a Style Guide
- All publishing organizations define a style guide for their published information. Such a guide supports teams to write in a similar tone, making it easier for readers to digest the information.
- Maintain a Glossary
- To enforce a common understanding of the domain, a glossary should define the terms important for the project. This also supports the ubiquitous language and makes sure nobody is left behind.
- Standard Layout
- A standard layout makes it easier for new members of a team to find information. A standard layout is project independent and is typically defined by an organisation.
Resources
For more information regarding this practice please refer to:
- Document Types and Templates
- Document types (or doctypes for short) define a set of properties and sections. Each doctype matches at least one Confluence Page Blueprint. Confluence Page Blueprints are a collection of templates, but often the collection contains only one element.
- Glossary
- To work with a domain everybody needs to use the terms unerringly. Create a glossary to create a common understanding of your domains.
- Glossary Item
- Glossary items are part of the domain glossary for the project. Glossaries support the team to use terms of the domain consistently in conversations and documentation.
- References
- For a document the references section contains pointers to resources that prove the statements of the document.
- Resources
- Provides references to further information to the topic of the document.
- Description
- Describes the content and the intention of the document instance. This is a longer form of the short description document property.
- Short Description
- The short description describes the content of the document. This information is typically displayed in document lists, where the name is rendered side by side with the short description.
- Experience Level
- Defines the context through which readers acquire skills. The level sets the expectation on the author's techniques to teach.
- Audience
- The audience is the group of readers the document defines as it target.
