Running Just-in-Time

To allow documents that answer questions of a group of stakeholders to be created just-in-time we need two principles in our team communication:

1. Create modular documents
2. Use Automation

Modular documentation consists of documentation modules. Each module answers one question. This makes it easier to combine modules to a larger document.

Automation is important to derive information from existing artifacts. This is quite similar to the reuse concept of modular documentation. Suppose your team created an API documentation in the source code or uses annotations. This information can be extracted and presented as modules to the document authors.

Both principles allow to reuse information and keep this information in one place. This not only reduces redundancies (which - if uncontrolled - increase the maintenance costs of documentation), but also makes it easier for authors to create new views on topics for a specific audience.

In this tip we focus on modular documentation.

How to start?

The projectdoc Toolbox provides the Module, Topic, and Section Doctypes to create a modular documentation.

• Modules are designed for reuse
• Topics stand by their own
• Sections allow to subdivide larger documents

Use the doctype's homepages as repositories of information in a given format (see Think Repositories). Add Subjects, Categories and Tags to provide additional views on these documents to locate information quickly (see Finding without Searching and Finding without Searching - applied!).

Views on Topics

Categorizing information allows to reference related information on a list-basis. But these are not the only views for readers. With a specific audience in mind or a specific group of stakeholders, the author may focus on different aspects of the same topic. A bird's eye view on a product is typically different for different audiences, like customers, sponsors, or team members.

Views for audiences are typically created with the Tour Doctype. The author collects topics and arranges them in a sequence most suitable to forward the goal of the document. Tour documents typically use transclusion to from one document.

Export and Archive

Due to the nature of transclusion the tour document reflects the latest changes of the transcluded document parts. If you need to share the information with a group of people (which may or may not have access to the wiki) or you simply need to freeze one configuration at a given time, you need to make a static copy of the document.

We recommend to use Scroll Office by K15t for this job. If you have a tour document with transclusions the document can be easily saved as a Microsoft Word or PDF document. In this form the document can be easily handed to stakeholders who have no time or privileges to access the wiki space. The format also indicates that the document contains a snapshot of information. The current information in the wiki is still authoritative in developing the next version.

The documents should be attached. Logging who has been sent a version document at which time may also help to keep track of interesting parties.

Resources

More information on this and related topics.