Cropmark

Technical spec template

A design document should let a reviewer understand a change without a meeting: the context, the architecture, the limits and the open questions. This template has each section, a linked table of contents, and two Mermaid diagrams you can edit in place.

What each section is for

  • Context

    The problem, in a paragraph a newcomer understands.

  • Architecture

    One diagram of the parts and how data moves between them.

  • Limits

    The numbers that bound the design, each with the reason behind it.

  • Open questions

    What is not decided yet, so reviewers know where to push.

Questions

How do I edit the diagrams?

They are Mermaid code blocks: change the text and the diagram redraws. See Mermaid to PDF.

Does the table of contents update itself?

Yes. [TOC] lists the current ## and ### headings each time the document renders.

Updated .