Skip to content

Stedi on writing a doc

Writing a doc is not a perfunctory gesture, and asking someone for a doc on something is not a punishment or a mechanism for control.

Writing a doc is a way of:

  • surfacing requirements and assumptions, and
  • driving clarity of reasoning stemming from those requirements and assumptions.

Without this step, our software has little hope of delivering the results we want over the long term.

Note that a doc doesn’t necessarily have to take the form of prose – in some cases, the right format for a doc could be a proposed API spec with bullet point lists of constraints, principles, or requirements. The goal of a doc is to reify your thinking and to share it with others.

As a final thought, not everyone has to write docs here. Some people just want to execute, and there is plenty of room for that, too – but if you just want to execute, you’ll be executing on the plan, architecture, or implementation described in someone else’s doc. Our domain is too complex, and our ambitions are too large to build software willy-nilly.

Stedi – The unwritten laws of engineering at Stedi

I'd love to hear your thoughts and recommended resources...