Documents should not reference details in other documents that may change without notice.

If a document refers to a detail in another document, this detail may not be part of the document in a later revision. While referencing documents is easy and stable within a wiki, referencing sections is not. Change the title of a page will change the links to it. Changing the name of a section will not be reflected in the links pointing to it.

Documents should reference related documents that are likely to be changed when the document itself is changed. Documents that relate closely should also have a logical and maybe physical proximity. This makes it easier for readers and authors to find related information.

Related Practices

The following practices are related to this principle.

Frequency of Change: Consider content by the frequency of change. Group content in information sets that change in the same frequency. The most important category for changes is the record, which implies no change.

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.
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.

References

More information on this principle.

Law Of Demeter: The principle described as a pattern on wiki.c2.com.
Law of Demeter: 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