Documentation should appear to the reader as being written by one single person. Uniformity reduces the chance of astonishment. The principles applies to all areas of documentation, including style and organization.

A program should follow the `Law of Least Astonishment'. What is this law? It is simply that the program should always respond to the user in the way that astonishes him least.
Geoffrey James. The Tao of Programming. 1987

People are part of the system. The design should match the user's experience, expectations, and mental models.
J. H. Saltzer, Frans Kaashoek. Principles of computer system design: an introduction. 2009

Same things should be handled the same. Similar things should be handled similar. This way readers have an easier job to locate the information they are looking for.

Readers expect a common structure for documents and the documentation. Diagrams and language should be similar throughout the documentation.

Consistency increases the predictability and reduce distraction. Systems following this principle are easier to learn.

Related Practices

The following practices are related to this principle.

Categorize: Organize content by keywords.
Describe Content: To make it easier for readers to determine the relevance of a document, there should be short description for each document.
Document State: To set the expectation right it is useful to communicate the state of each document to the collaborating authors and the readers.
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.
Know your Mission: Use charters to define the purpose and benefit of each document. State the expectation of the stakeholders involved.
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.
Make Reader feel Home: Communicate in a way expected by the reader.
No Noise: Do not render text to the reader that has no information value.
Single Point of Access: Users require a single point of access to all information relevant for a project.
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.
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.

Related Principles

The following principles are related to this principle.

DRY Principle: Redundant information is hard to maintain, keeping it in-sync. Therefore strive for reducing redundancy by defining one authoritative location for each piece of information.
KISS Principle: Keep your documentation simple. Assume that authors have relevant information for the project in their mind, but not necessarily the skills and resources to communicate it. Therefore make it very simply and joyful for them to share their expertise.
Law of Demeter: Documents should not reference details in other documents that may change without notice.
Open Closed Principle: Be open for extension, closed for modification.
Self Documentation Principle: There should either be no need for additional documentation for an artifact or that documentation should be as close as possible to the artifact. This make it more probable that the documentation changes with the artifact and therefore keeps up-to-date.
Separation of Concerns: Reduce the amount of documents with overlapping information. Also divide the concerns regarding the formatting and - as far as possible - the structure from the content. Whenever there are different aspects, consider if handling them independently would make things easier.
Single Responsibility Principle: A document should focus to answer one question. This way documents can be more easily reused and combined.
Stable Dependencies Principle: A document should only reference documents that are not less stable than itself.
YAGNI Principle: Assume that an information is not needed to be written down unless proven otherwise.

References

More information on this principle.

Principle Of Least Astonishment: The principle described as a pattern on wiki.c2.com.
Principle of least astonishment: The principle described on Wikipedia.

pattern

Space shortcuts

Page tree

Docs

Support

Free Blueprints

Tooling for Blueprints

Free Extensions

Spaces

Plugins for Maven

Incubator

Libraries for Java

Incubator

Add-ons for Confluence

Tools

Support

Team

Legal

Related Practices

Related Principles

References

About

Keep up-to-date!

Powered by