Technical documentation standards
Technical documentation ensures the traceability, maintainability, and understanding of Crehana's systems. This standard establishes a common base for documenting technical changes in a way that is clear, proportional, and useful for engineering.
Why it exists
As products and services evolve, changes — large or small — impact multiple components, teams, and flows. Without clear and consistent documentation, knowledge ends up scattered across code, tickets, or conversations, which makes maintenance and future decision-making harder.
Purpose
- Provide a shared language and structure for documenting technical changes.
- Enable historical traceability of decisions and modifications in the system.
- Reduce the dependency on implicit or tribal knowledge.
- Ensure that any engineer can understand the changes over time.
- Keep the balance between good documentation and agility.
These standards do not replace product documents such as the PRD: they complement them from a purely technical perspective.
Scope
The standards apply to:
- Changes in backend, frontend, and data.
- Services, subgraphs, APIs, workers, and batch processes.
- Changes in behavior, business rules, performance, or architecture.
They do not cover:
- Definition of business problems.
- Goals, KPIs, user stories, or functional product flows: those live in the PRD.
Principles
- Documentation is a help, not a burden. It brings clarity and value; it avoids unnecessary bureaucracy.
- The level of detail is proportional to the impact. Not every change requires the same depth.
- Traceability matters more than length. A short, clear document beats a long one that is hard to maintain.
- Documentation evolves with the system. It is not a static artifact: it is updated when the behavior changes.
Companion documents
The standard relies on two documents that still live in Confluence:
- Plantilla de documentación técnica — defines the base structure for documenting a technical change: consistent writing, relevant information that is not omitted, and easy reading across teams. Adapt the template to the type and size of the change: fill in only the sections that apply.
- Estándar de documentación técnica por nivel de cambio — defines what to document depending on the impact of the change: small, medium, or large. Use it to determine the expected level of detail, avoid over-documenting small changes, and ensure enough context for higher-impact ones.