this repo has no description
📝 Add technical specifications note
+20
-1
+1
-1
Design Docs.md
+1
-1
Design Docs.md
···
5
5
- These are relatively informal documents that the primary author or authors of a software system or application create before they embark on the coding project. If code is the bricks and mortar, then these docs are the blueprints.
6
6
- Short specs are more likely to be read. The purpose of a spec is to briefly communicate the "why", "what" and "how" of the project to the rest of the team. Ideally these short documents force teams to scope out work so priorities are clear and teams avoid building the wrong thing.
7
7
- [The longer your document is, the more likely people will only read the comments and not the body.](https://twitter.com/hamiltonulmer/status/1562817324184440832)
8
-
- A tech spec forces you to think through complicated issues and to get everyone on the same page. This helps to avoid wasting time on dead-end solutions or building the wrong thing.
8
+
- A [[Technical Specifications]] forces you to think through complicated issues and to get everyone on the same page. This helps to avoid wasting time on dead-end solutions or building the wrong thing.
9
9
- It's hard to make technical decisions while remote. [Build a Proposal Culture](https://web.archive.org/web/20220925011031/https://www.hamiltonulmer.com/writing/building-a-proposal-culture) to enable effective distributed technical decision making via [[Writing]] and collecting [[Feedback]] on a written document in an inclusive, async-friendly way.
10
10
- Even if no one else reads them, they force you to clarify my thinking before you start the (more expensive) process of implementation.
11
11
- Design docs fulfill the following functions in the software development life-cycle:
+19
Technical Specifications.md
+19
Technical Specifications.md
···
1
+
# Technical Specifications
2
+
3
+
A technical specification is a written design artifact you use to think before coding, align stakeholders, and define what "done" means. It sits between [[Design Docs]] and [[Documentation]].
4
+
5
+
- Should be broad enough to explain the problem and trade-offs, but precise enough that someone else can implement and operate the change.
6
+
- Start from the problem, not the implementation. [Clarify the problem, context, goals, non-goals, assumptions, proposed solution, rollout, risks, and success metrics before you write code](https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/). The main value is forcing you to scope the work, expose edge cases early, and align reviewers.
7
+
- Make the spec precise where interfaces and operations matter.
8
+
- [Once a spec is detailed enough to generate reliable software, it starts to look like code or pseudocode](https://haskellforall.com/2026/03/a-sufficiently-detailed-spec-is-code). Use specs to improve [[thinking]] and coordination, not to skip precision.
9
+
10
+
## Key Sections
11
+
12
+
- **Metadata**. Add the title, authors, reviewers, status, dates, and linked tickets so the document has clear accountability and revision context.
13
+
- **Problem Statement and Context**. Explain the user or operational problem, why it matters, the relevant background, and the boundary of the system you are changing.
14
+
- **Goals, non-goals, and assumptions**. State what success includes, what is explicitly out of scope, and what conditions you rely on so reviewers can challenge scope early.
15
+
- **System overview and architecture**. Outline the main components, abstraction layers, dependencies, and how the pieces fit together before you dive into implementation detail.
16
+
- **Domain model, interfaces, and invariants**. Define the important entities, data shapes, APIs or contracts, state machines, and normalization rules precisely enough that implementers make the same decisions.
17
+
- **Execution, failure, and safety model**. Describe the main flows, failure modes, recovery behavior, trust boundaries, and operational safety rules for the system you are proposing.
18
+
- **Test, rollout, and observability plan**. Say how you will validate the change, measure it in production, deploy it, and roll it back if needed.
19
+
- **Alternatives, risks, open questions, and definition of done**. Record trade-offs, unresolved decisions, success metrics, milestones, and the checklist that marks the work complete.