Engineering leadership

Docs as artefacts

Evergreenupdated English1 min read

Open in the cabin →

Sample note, replace me.

A meeting produces a feeling of agreement. A document produces an artefact: something you can point at, link to, disagree with line by line and come back to in six months. Teams that treat documents as the work, not as paperwork about the work, move faster with fewer people in the room.

What makes a document an artefact

It has an owner, a date and a status. It says what was decided and what was rejected, and why. It is short enough to be read before anyone is asked for an opinion.

KindAnswersLives for
ProposalShould we do this?Until decided
Decision recordWhat did we pick, and what did we drop?Years
RunbookWhat do I do at 3 AM?As long as the system
Weekly noteWhat changed?A quarter

Rules of thumb

  • Write the summary first. If you cannot, you do not know what you think yet.
  • One decision per document.
  • Comments are cheap, meetings are expensive: ask for comments first.
  • Close the loop. A proposal without a recorded outcome is noise.

This only works when people have time to read, which is the point of Meeting-free Fridays. It also pairs well with ruthless scope: see cut eighty percent (in Turkish).

When not to write

Do not write a document to avoid a conversation. If two people are stuck, a ten minute call beats a ten comment thread. Write down what you agreed afterwards.

Tags: writing, async, teams

Linked from

  • Yüzde seksenini kes

    Bir ürünü iyi yapan şey eklenenler değil, çıkarılanlardır. Kapsamın yüzde seksenini kesmek çoğu zaman en hızlı ve en dürüst yoldur.

    FilizTürkçe1 dk okuma

  • Meeting-free Fridays

    One day a week with no meetings is the cheapest productivity tool a team can adopt, and the easiest to lose.

    GrowingEnglish1 min read