To set the expectation right it is useful to communicate the state of each document to the collaborating authors and the readers.

Documents are created by the team. When a single team member starts a document, there may be an idea for a topic that should also be explained in more detail. The team member should be able to focus on the document at hand and also be empowered to leave notes for other topics at the right places.

Other team members should not be distracted by documents at different levels of evolvement. They should be able to determine the current level of the document easily.

How can documents be created incrementally by a team of authors without distracting or annoying readers with unfinished work?

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.

No Noise
Do not render text to the reader that has no information value.

Resources

For more information regarding this practice please refer to:

Iteration Macro
Selects an iteration phase from a fixed set of stages.
Pending Box Macro
Renders a box containing a pending message to be handled later by the author.
Feedback Box Macro
Renders a box containing a feedback message from a reader with write privilege.
Fault Box Macro
Renders a box containing a fault message reported by a team member for the author.