- Created by Robert Reiner, last modified on 22. Jun 2023
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.
- Domain
- Type
- Principles
Teams need to organize information it needs to communicate to stakeholders and within the team.
While it is easy to add new documents, it is increasingly cumbersome to find documents that need to be updated due to a given change. It may also be difficult to determine the relevance of a piece of information for the future.
Not knowing the frequency of change may result in falling into the maintenance cost trap when teams add information on an ad-hoc basis.
The team is loaded with large amounts of maintenance work. It is unclear for stakeholders, which documents are up-to-date and which are not.
In this context it typically also gets more and more difficult for the team to determine which parts of the documentation is still relevant for the project and which needs to be continuously updated. The team is also in demand to keep the number of outdated documents close to zero.
Structure
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.
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.
Document vs. Record
A special case of this practice is distinguishing documents (that have to be updated) from records (that need not to be updated).
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.
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. Records sometimes appear in the form of reports.
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.
Stakeholders should always be clear about whether a given piece of information is part of a document or a 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.
Create 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:
- Documents that never change (records)
- Documents that regularly change (automatically generated documents)
- Documents that change less frequently
- 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).
Referencing
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.
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.
Advantages
To distinguish between records and documents is typically a big step to control the maintenance costs for documentation.
This practice makes the team aware of these costs and provides a rule of thumb to handle documents and records.
Disadvantages
While the practices creates some level of sensitivity to the maintenance problem it provides no strict guidelines on how to create this organization.
This practice supports authors. Readers should not be concerned with the frequency of change, since they should assume that all documents are up-to-date.
This practice may lead to a technical organization (by the property frequency of change) of the documentation where an organization based on the content is typically more meaningful. Therefore consider this practice as a subordinate organization scheme. It is a good practice to have the journal of a team member (personal space) or the iteration documentation of an agile team into a separate space.
Alternative technical organizations (such as access restrictions) may be more important to get right than the frequency of change.
Related Practices
The following practices are related to this practice.
- Keep a Journal
- In order to take personal notes on one's own work and to reflect upon what has to be done or has been done, keep a journal. The information in the journal should be shareable at least with all team members.
- Provide multiple Views
- Provide views on your topic-based documentation.
- Physical Location
- Store information physically only by properties that are invariant.
Resources
For more information regarding this practice please refer to:
- projectdoc Developer Diaries
- Provides doctypes to organize the developer's work by the employment of a diary. Take you personal planning and professional records to the next level!
- Doctypes for Agile Planning
- Provides doctypes to collborate with your team. Run iterations and record discoveries that may be of interest at the end of the iteration or for even later reference. Quick notes are more easily added as records to the team's space than to the official documentation tree. Defer the talk to the documentation architect to the end of the iteration (if the discovery is still of interest).
- Create a Workspace
- Create a space to work on a given topic. This spaces uses an index space to reuse content.
