Date: Fri, 29 Mar 2024 02:54:26 +0100 (CET) Message-ID: <771733626.17613.1711677266688@09e9d69a2016> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_17612_551775256.1711677266688" ------=_Part_17612_551775256.1711677266688 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
Consider content by the f= requency of change. Group content in information sets that change in the sa= me frequency. The most important category for changes is the record, which = implies no change.
Teams need to organize information it needs to communicate to stakeholde= rs 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 b= e difficult to determine the relevance of a piece of information for the fu= ture.
Not knowing the frequency of change may result in falling into the maint= enance 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 t= eam 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 de= mand to keep the number of outdated documents close to zero.
Take the frequency of change of a document into account at the moment th= e request for creating the document is considered. This sets the expectatio= n of all stakeholders interested in the document.
Try to keep documents with a given frequency of change in one space. Thi= s will result in spaces with relatively stable documents and spaces where c= hanges need to be applied often.
Views al= low to decouple the physical location from the logical location of a docume= nt. This makes it possible to store documents by stable technical propertie= s that do not change instead of semantic physical locations.
A special case of this practice is distinguishing documents (that have t= o be updated) from records (that need not to be updated).
Documents contain information that needs to be updated. The cost of a do= cument is therefore not only the cost of creating it initially. The stakeho= lder in need of the information provided by the document has to take care o= f maintenance costs that arise due to required updates. Documents have diff= erent frequencies of change, therefore some documents have higher maintenan= ce costs than others.
A record is a representation that stores the information of an event. Th= e information is immutable and therefore does not need to get updated. The = maintenance costs of records is therefore very low or zero. The determinati= on which pages are records and which are not is the most important applicat= ion of this practice. Records sometimes appear in the form of reports= em>.
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 th= e team or public documentation. Journals also exist for teams to manage inf= ormation collected during a sprint.
Stakeholders should always be clear about whether a given piece of infor= mation is part of a document or a record.
If a stakeholder demands a defined piece of information the team that cr= eates this document must determine if the stakeholder assumes that the docu= ment 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 th= e 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 deliver= ed. When the stakeholder needs a current version of the document the work f= or creating a new record based on the information of the previous record ca= n be scheduled for the next iteration.
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= :
Try to minimize documents in category four by turning them into records = or by trying to generate them from artifacts (automation).
This practice also implies that documents that change less frequently sh= ould not rely on information that changes frequently. This is especially th= e 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 beca= use the document has a set of properties (dynamic links). This is because the links are automat= ically updated.
A process document may refer to the location where meeting notes are sto= red. As long as the process document makes no assumption on information on = the meeting notes (e.g. their number or latest creation time), the principl= e is not violated.
It makes no difference whether the information is referenced with a link= or actually transcluded.
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.
While the practices creates some level of sensitivity to the maintenance= problem it provides no strict guidelines on how to create this organizatio= n.
This practice supports authors. Readers should not be conce= rned with the frequency of change, since they should assume that all docume= nts are up-to-date.
This practice may lead to a technical organization (by the property freq= uency of change) of the documentation where an organization based on the co= ntent is typically more meaningful. Therefore consider this practice as a s= ubordinate organization scheme. It is a good practice to have the journal o= f a team member (p= ersonal space) or the iteration documentation of an agile team into a s= eparate space.
Alternative technical organizations (such as access restrictions) may be= more important to get right than the frequency of change.
The following practices are related to this practice.
For more information regarding this practice please refer to: