As discussed in Part 1, Configuration Management is an unsolved problem. Or rather, two problems:

1. Our document-writing tools are fundamentally uncollaborative, fussy, and don’t natively support critical CM functions.
2. The CM tools we wrap around documents rely on serial, heavy-weight, and monolithic approval cycles that are inherently slow and restart whenever they uncover conflicts or mistakes. This reduces velocity and incentivizes people to either approve work that is low-quality (but passable) just to end the slog, or insist on needless perfection, because they don’t want to have to go through it again any time soon.

Enter the Web

The internet, or more specifically the World Wide Web, solved some of these problems:

• URLs uniquely identify pages, eliminate reliance on a user-facing file system to organize content, and excel at cross-referencing.
• ⌘-F (a.k.a. “find”) obviates the need for navigation tables or acronym lists, since both were invented to provide an easy way tofind information.
• The separation of content (html) and formatting (CSS) help reduce fiddling, as does the lack of pagination.

But the basic Web is an individual publishing platform, and it doesn’t natively address key collaboration challenges.

Wikis FTW

Wikis (I’m most familiar with Atlassian’s Confluence) are built on the Web’s foundation and provide several key features:

• A single source of truth: There is one current page that everyone sees. When files are squirreled away in email and scattered on file servers, it’s hard to figure out how they are all related and which copy branched off of which.
• Revision tracking: But revisions are stored, in a single, linear history. This encourages people to make updates, because changes are easy to revert. Critically, this is automatic: no one has to do anything to ensure all revisions are saved.
• Revision logging: It’s always clear who made a change. This increases accountability, makes it easier to follow up with people, and discourages petty behavior like vandalism or edit wars (unlike on the internet at large, you are not anonymous at work).
• Revision comparison, so it’s easy see what’s changed between any two updates (more on this later).
• Collaborative real-time edits and comments: Multiple people can edit at the same time, and everyone can see everyone else’s comments, so conflicts are identified as early as possible. This also means reviewers can work in sprints, instead of feeling like they have to finish their entire review before sharing any feedback.

So a good wiki mostly solves the collaboration and revision history problem, but what about actual configuration management? We need a new paradigm for the review and approval of baselines.

A New Approval Paradigm

A baseline is nothing more than a revision with special status because it has been reviewed and approved by whatever cabal your culture grants that authority. The trick is how to add a high-velocity and low-friction review and approval mechanism to a wiki.

I think the secret is just a slight shift in how information is presented: we change the default view from latest to diff. So not this:

• For Whom the Bell Tolls
• Omit needless words.
• Jane

But this:

• For Who Whom the Bell Tolls
• Omit any explanations or descriptions that you deem needless, as these excess words detract from the clarity and concision of your message.
• Jane came into the room and sat down on the blue couch.

During the initial, pre-baseline writing process, the diff is between the last two revisions. But when we select approvers, it marks the current revision as a baseline, and until any subsequent edit is approved, the default view is a diff between that baseline and the latest revision. So at first folks see a clean copy, and if the document is perfect they can approve as-is.

But they can also leave comments, respond to comments others have made, or directly edit the page. Edits show up as diffs, and the author and other approvers have a user interface to accept these changes (and/or make more). If a change is accepted by all approvers it establishes a new baseline, and the diff disappears.

The change seems simple, but in practice I think it would be profound for several reasons. First, baseline changes can be approved piecemeal. Little typos are going to be accepted immediately,¹ and substantiative debates about one portion of a document won’t hold up uncontroversial improvements elsewhere. Second, it focuses attention on changes, but without taking them out of context, so subsequent reviews can be more focused and quicker. Third, it eliminates the barrier to entry for improving a released document, because the author knows the changes will be visible to everyone immediately, but also highlighted in a way to indicate they’re not yet blessed.

In short, this interface better reflects the truth: we have a baseline, and it has been approved, but someone thinks it can be improved in this specific way. And it begs people to approve, or improve, the proposed changes.

Most configuration management systems get to quality products by slowing things down, increasing friction, and establishing gates, but they make it so hard to release documents that we delay their use as long as possible and then use them as infrequently as possible. The result may be high-quality, but not for long.

Instead, by bulding on a web-based publishing platform and making it easy to fix mistakes and approve proposed changes, we establish an entirely new CM paradigm that strips away the cruft of the paper-based past, encourages collaboration, and incentivizes frequent marginal improvement.