Documentation: Less Is More

1 link


Updated March 23, 2023

You’re reading an excerpt of The Holloway Guide to Remote Work, a book by Katie Wilde, Juan Pablo Buriticá, and over 50 other contributors. It is the most comprehensive resource on building, managing, and adapting to working with distributed teams. Purchase the book to support the author and the ad-free Holloway reading experience. You get instant digital access, 800 links and references, a library of tools for remote-friendly work, commentary and future updates, and a high-quality PDF download.

When building a distributed team, you may be tempted to require every member to write everything down. But an overabundance of information can be as problematic as the lack of it—overabundance makes it harder for remote teams to filter what is signal and what is noise.

Instead of writing everything down, an effective distributed team will focus on how to write what matters.

The clarity of information isn’t directly related to the quantity of information, but rather the quality, and surrounding context for it. As you determine the ways in which you will communicate as a distributed team, you’ll want to create a collective understanding of what to communicate, and how to communicate it in a way that shortens or eliminates physical, temporal, and cultural distances.

importantHolloway co-founder Josh Levy has proposed a principle of documentation that is applicable to distributed teams. The OAC principle posits that any documentation should have clearly defined Ownership, Author, and Cadence:

  • Owner. This is the one person ultimately responsible for the doc. Documents should never be owned by “everyone” or “no one in particular.”

  • Audience. Is it company internal, project or group internal, for external customers, or for the whole web?

  • Cadence. What is the cadence of updates, if any? This means, what is the workflow for updating and what is the lifespan? Some options:

    • Fixed lifespan. Write, use, later archive. This could be collaborative or done by one person.
    • Long lived. Maintained and updated by the owner or others. This could be ad hoc or on a schedule. There are also variations on workflow here, such as welcoming suggestions from anyone, but keeping review and acceptance by the owner.

If for each doc or folder you create, you know the answer to these three things, your docs will be better organized, better used, and better maintained.

If you found this post worthwhile, please share!