Structure

Add a property to each document that describes the level of evolvement. This property is called iteration.

When a new document is created, the title and short description should tell everyone on the team about what this document is about to cover. This first iteration is called facade. The document is simply a reminder for a topic to document. Once the team adds notes about what the contents of the document could be, the document enters the filled iteration. When the team decides that all information is there and should be put into shape, the focus iteration starts. Bringing into shape also includes pruning. In the last iteration, which is called finished, the text and illustrations are polished.

After this last iteration of creating the document the team is ready for publishing it. There may be a number of publishing steps (within the team, within the company, to customers) that may apply changes to the document.

If changes need to be applied to a document, it may be put back to the filled iteration and the team starts to collect new information on that document.

The state of the document may be listed in dynamic lists. Especially in the facade state a reader will know that there is no need to follow the link.

While collaborating on creating a document, boxes (pending box, feedback box, and fault box) and sections only rendered for readers with write access.

Advantages

• The state of the document can be seen with one glance
• Readers know to which level the information in the document can be trusted
• Documents can be created and evolved as a team by collectively adding information in the filled iteration
• In the focus and finished iteration a single team member may conduct the work (typically two different team members)
• All team members have the chance to participate in the creation of the document
• Due to the four defined states a larger number of team members has the chance to get information about the topic

Disadvantages

• The iteration property of a document needs to be set manually
• The iteration steps may be more blurry than the seem in first place
• For internal documents there will be no focus or finished iteration since the investment will not pay back

Related Practices

The following practices are related to this practice.

Resources

For more information regarding this practice please refer to: