Documenting Assumptions
Learn how to document architecture assumptions using NeoArc's structured assumption blocks. Capture what you are betting on so you know what to revisit when circumstances change.
Every architecture rests on assumptions. You assume the database can handle the expected load. You assume the third-party API will remain available. You assume the team has the skills to implement the chosen technology. When these assumptions are wrong, architectures fail.
Adding an Assumption Block
Assumption Block Fields
Type
Categorise the assumption:
This example uses the NeoArc Assumption content block.
Confidence
How confident are you in this assumption?
| Confidence | Meaning | Action |
|---|---|---|
| High | Strong evidence supports this | Monitor periodically |
| Medium | Reasonable expectation but not proven | Validate when feasible |
| Low | Educated guess, needs validation | Validate early |
This example uses the NeoArc Assumption content block.
Status
Track the lifecycle of assumptions:
This example uses the NeoArc Assumption content block.
Types of Assumptions
Technical Assumptions
Bets on technology capabilities:
This example uses the NeoArc Assumption content block.
Organisational Assumptions
Bets on people and processes:
This example uses the NeoArc Assumption content block.
Writing Good Assumptions
Effective assumptions are:
| Quality | Description |
|---|---|
| Explicit | State clearly what you are betting on |
| Specific | Include numbers, timeframes, and conditions |
| Testable | Define how to validate them |
| Connected | Link to the decisions that depend on them |
When Assumptions Are Wrong
When an assumption proves false:
Documented assumptions make this manageable. Undocumented assumptions make it chaotic.
You will find assumption blocks used throughout this documentation site wherever we document design bets. The structured format makes assumptions visible, trackable, and actionable.