You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 3 Next »

 

A document should only reference documents that are not less stable than itself.

The principle controls the probability of changes to a document introduced by changes to document it references.

If a document references documents that are more likely to change and therefore are less stable, there is a great chance that the information in this document also needs to be updated. If not, the reference to the other documents is probably not relevant and may be removed.

Note that dynamic navigation links are excepted from this principle, since they adapt automatically to changes. This is under the assumption that the keywords used to determine the inclusion of a link to the list is based on the content. Changes to the content will result in changes to the keywords if appropriate.

Related Practices

The following practices are related to this principle.

Favor flat Hierarchies
Organize information physically in flat hierarchies. Add views to put these documents in different contexts.
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.
Physical Location
Store information physically only by properties that are invariant.
Welded Lifespan
If documents are added as children to a document, these documents share the lifespan of the parent. If the parent is removed, so are the children.

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

Stable Dependencies Principle
The principle described as a pattern on wiki.c2.com.
Package principles
The principle described on Wikipedia.
  • No labels