ADR-002: Documentation versioning strategy
Status
Accepted
Context
Balyze includes a growing body of technical documentation.
Early in the project, a decision was required regarding how documentation should be versioned in relation to the product itself.
Potential approaches included:
- strict coupling between code and documentation versions
- independent documentation versioning
- multi-version documentation hosting
At the ALPHA stage, simplicity and maintainability are prioritized over completeness.
Decision
The technical documentation is versioned independently from the application code.
The following strategy is adopted:
- the
mainbranch represents the current validated state of the documentation - the online documentation always reflects the latest state of
main - major documentation milestones are marked using Git tags
- documentation pages explicitly indicate their applicable product phase (e.g. ALPHA)
No multi-version documentation hosting is implemented at this stage.
Rationale
This approach:
- avoids premature complexity
- allows documentation to evolve continuously
- supports clear historical reference via Git tags
- keeps the documentation workflow lightweight
The documentation remains authoritative for the current state of the product.
Consequences
Positive
- simple and predictable workflow
- no branching overhead
- easy onboarding for contributors
- no tooling lock-in
Trade-offs
- older documentation versions are not directly browsable online
- historical states require checking out Git tags
These trade-offs are acceptable at the ALPHA stage.
Future considerations
As the product reaches BETA or v1:
- multi-version documentation tools (e.g.
mike) may be introduced - documentation versions may align more closely with product releases
Such changes will require a new architectural decision.