Patterns

Decisions Pattern

A common use of documentation on teams is to take notes around research. When that research is to make a decision, I have found this decision pattern to help keep from ending with too many unfinished pages which happen when the team ultimately makes a decision and then leaves all the research pages lying about.

Step 1: Decisions Aggregate Page

Create a Decisions top-level page that only lists all the decisions pages.

Step 2: Create a Decision Template

Create a template which contains all of the details you want to have about a decision. Minimally, the template should include:

• Table of Contents
• Overview with Excerpt - to be leveraged in annotated aggregate pages
• Decision - highlighted in a way at the top
• Analysis - could extend to multiple sections or additional pages going over the research and analysis

Step 3: Archive Completed Decisions

Make one Completed Decisions aggregate page and move any completed decision into that section.

Benefits

This basic pattern ensures that team decisions are documented with the research provided. It ensures that past decisions can be reviewed by current or new team members - this can save a lot of time when a new team member or someone else not in the know wants to know why a decision was made. It ensures that research about a topic has a permanent location to live instead of cluttering up team documentation pages.

Over time, you may find this pattern helps the team to better hone decisions and become more disciplined about researching them.

Documentation Phases

Draft, review, and publish your documentation. Do not put your draft documentation in with your published documentation. It is important to adopt a page style guide and documentation publish pattern that allows you to draft and review before you publish.

We have all seen the endless numbers of incomplete documentation pages in team docs that are clearly not finished but which also lack any information about why.

Locations

Some locations to consider staging documentation:

• Personal space - draft notes not ready to share with the team
• Team space - notes ready for review or beneficial to the team but not ready or necessary for wider audience
• Published space - only notes that have been reviewed