Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Section
titleStructure

Take the frequency of change of a document into account at the moment the request for creating the document is considered. This sets the expectation of all stakeholders interested in the document.

Try to keep documents with a given frequency of change in one space. This will result in spaces with relatively stable documents and spaces where changes need to be applied often.

Example Box

Views allow to decouple the physical location from the logical location of a document. This makes it possible to store documents by stable technical properties that do not change instead of semantic physical locations.

Section
titleRecord vs. Document

A special case of this practice is distinguishing records (that need not to be updated) from documents (that have to be updated).

A record is a representation that stores the information of an event. The information is immutable and therefore does not need to get updated. The maintenance costs of records is therefore very low or zero. The determination which pages are records and which are not is the most important application of this practice.

Documents contain information that needs to be updated. The cost of a document is therefore not only the cost of creating it initially. The stakeholder in need of the information provided by the document has to take care of maintenance costs that arise due to required updates. Documents have different frequencies of change, therefore some documents have higher maintenance costs than others.

Example Box

Journal entries are per default not subject to change. Each entry is a record. Journals allow team members to take individual notes or develop a topic before it is part of the team or public documentation. Journals also exist for teams to manage information collected during a sprint.

Section
titleCreate Categories

It is sometimes quite difficult to determine the frequency of change for a document in advance. Therefore it is easier to think in these categories:

  1. Documents that never change (records)
  2. Documents that regularly change (automatically generated documents)
  3. Documents that change less frequently
  4. Documents that change frequently

Try to minimize documents in category four by turning them into records or by trying to generate them from artifacts (automation)Documents contain information that needs to be updated. The cost of a document is therefore not only the cost of creating it initially. The stakeholder in need of the information provided by the document has to take care of maintenance costs that arise due to required updates. Documents have different frequencies of change, therefore some documents have higher maintenance costs than others.

Example Box
titleDocument to Record

If a stakeholder demands a defined piece of information the team that creates this document must determine if the stakeholder assumes that the document reflects the current state of the project at any time. If this is true, the stakeholder is required to asset a certain amount of resources for the update of this document.

The team should make clear that handling the document as a record is an option for the stakeholder. The report is current at the time it is delivered. When the stakeholder needs a current version of the document the work for creating a new record based on the information of the previous record can be scheduled for the next iteration.

Section
titleCreate Categories

It is sometimes quite difficult to determine the frequency of change for a document in advance. Therefore it is easier to think in these categories:

  1. Documents that never change (records)
  2. Documents that regularly change (automatically generated documents)
  3. Documents that change less frequently
  4. Documents that change frequently

Try to minimize documents in category four by turning them into records or by trying to generate them from artifacts (automation).

Section
titleReferencing

This practice also implies that documents that change less frequently should not rely on information that changes frequently. This is especially the case if the document refers to the information in the referenced document (for instance a link to an HTML anchor).

Referencing is no problem if there is simply a link to the document because the document has a set of properties (dynamic links). This is because the links are automatically updated.

Example Box

A process document may refer to the location where meeting notes are stored. As long as the process document makes no assumption on information on the meeting notes (e.g. their number or latest creation time), the principle is not violated.

It makes no difference whether the information is referenced with a link or actually transcluded.

...