A Few More Words

We can find key information. Key information is whatever anyone needs to do their work.

So what? What can we do to get there? What are you going to go about it?

People have many opportunities to document. We make the choice to document, or not, all the time…

• Making a decision, evaluating options
• Discussing requirements with a user
• Today’s task list
• While programming
• Asking how to use an application’s feature

…But, when do we choose to document? Usually when we are forced to, or the ‘doing’ of a task is assisted by a document…

• Recording pros and cons for various options
• Draw a user interface layout on a whiteboard
• Write your task list on a post-it note
• Pseudo code to explore design options
• Email a question to application support

…But, when do we want to keep a document? There is no easy answer, something will be useful if it is ever used. (Beyond the base requirements of whatever process we may have in place), we are empowered to capture information based on our judgement of importance balancing cost and value.

So, what does it take to move documentation, that was functional during a task, to something suitable for keeping? Effort.

Ideally we want to reduce that effort to zero so that we have a ‘documentation reflex’ that automatically harvests daily opportunities…for example:

• Recording options in a Word document.
• Having a whiteboard that will email its user interface drawing to you (so you can attach it to a change request).
• Change from post-it note to task management software.
• Write pseudo code in your development tool as code comments.
• Post a question to an application forum.

Note: to encourage updates, the effort to change these ‘functional’ documents should also be minimal, and in many cases authorship should be shared (so that everyone feels able to make a change).

In addition to simple opportunities, we may have requirements for specific documentation. These requirements are usually more formal, and are made evident through business or process requirements…

• Production Change Request
• Application training

These become project deliverables in their own right - you just have to sit down and put effort into creating them.

An important difference, when capturing documents, is that some are created, and others evolve. Some documentation will record a moment in time (like a diary) for example: options analysis, a decision, or meeting minutes. Whereas others will need constant change, for example: application training, comments within the source code, or a process checklist.

There is a grey area for what is a ‘created’ or ‘evolving’ document. For example the user interface design captured via a whiteboard. If the user requests a change, should the already documented user interface be revisited, or just the change request be captured? The choice in this case comes back to what you have identified as important to capture. Do you accept the initial design and change requests as diary-like documents, with the built system reflecting the current user interface? Or do you need to have an up-to-date model of the user interface?

Making the choice for an evolving document is more expensive. So, a guideline can be to make a ‘created’ document the default output, then evolve that document as a considered decision.

In summary:

• Capture information as part of your work practices.
• Minimise the effort required to capture information.
• Create documents by default, evolve them by choice.