Documentation Standards

How We Do Documentation

Shared documentation is notoriously challenging for teams. It’s a classic “tragedy of the commons” situation - it’s often neglected because nobody owns it. Another issue is that even with the best intentions, documentation tends to be disorganized because every individual interprets the structure in their own way.

In this document I’m proposing we adopt a system where we elect a single person to take responsibility for the documentation for a period of time - a benevolent documentation dictator (or “Doc-tator”).

This person will have absolute power over how we structure our documentation, and can make updates quickly without having to achieve consensus.

Doctator Role

The doctator can define their own role to a large degree. I imagine they would not write or update all the documentation, but they would establish and enforce the system that enables people to maintain and use our documentation.

Communicating the structure is probably part of the job. Answering user’s questions is probably part of the job. But they might decide that a laissez faire approach is best and that the best documentation evolves organically. (I personally disagree with this.)

As with any elected official they are accountable to the voting public, so it behooves them to gather opinions and serve the needs of the users.

Starting March 1st a Doctator will be elected once a month by chat poll on the last day of the previous months. Elections will be quarterly after July 1st (Q3).

Alternative Approaches Considered

Here are some other options, and arguments against them:

Hold meetings where we sync on how to structure our documentation? Reaching consensus on this could be time-consuming, and is likely low priority for a lot of folks.
Laissez-faire - allow the documentation to grow organically. This is the default at many organizations, and can result in documentation that’s outdated or difficult to use.
Can we use Almanac’s version control to propose structural changes and get move things forward that way? That could also work.

If this proposal is accepted, this document will be updated to reflect what we agreed on.