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.
The DRY principle aims is the 'Don't Repeat Yourself' in documentation work. If the same information is added at different locations, it increases the cost of maintenance to track these locations in the case of a change.
Every piece of knowledge must have a single, unambiguous, authoritative representation within a system.wiki.c2.com. Dont Repeat Yourself
Some form of redundancies may actually help to reduce the documentation costs or support readers in understanding. But these redundancies should be added with care.
The following practices are related to this principle.
- Employ Delegate Documents
- Delegate documents make it easier to reuse content from existing documents as a whole.
- Employ Impersonator Documents
- Impersonator documents make it easier to reuse structure with different content.
- Employ Mapping Documents
- Mapping documents support adding information to the association of two (or more) documents.
- 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.
- Provide multiple Views
- Provide views on your topic-based documentation.
- Single Sourcing
- Reduce redundancy by having one source of truth for each information. This way the written information is more easily reusable in other documents and - which is even more important - it is referenceable. Single sourcing demands automation.
- 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.
The following principles are related to this principle.
- 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.
- Principle of least Astonishment
- 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.
- 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.
More information on this principle.