Context
Julee documentation exists in parallel forms: hand-written RST and autodoc-generated API docs. This creates drift, duplication, and maintenance burden.
The doctrine system establishes that tests ARE the specification. The same principle applies: docstrings ARE the documentation.
The Decision
-
Framework = Information Architecture, Content = Solution - julee provides semantic scaffolding; solutions provide content
-
Viewpoints Are Projections - Framework BCs (core, hcd, c4) become documentation viewpoints projecting solution content
-
Bespoke Templates Per Entity Type - Autodoc with entity-specific templates selected by doctrine-guaranteed structure
-
Directives Wrap Use Cases - list-stories wraps ListStoriesUseCase
-
Code Exists → Autodoc; Code Doesn't Exist → Design Doc - Hand-written RST only for unimplemented features
Why an ADR?
This decision:
- Eliminates documentation drift (generated from code)
- Creates navigable dependency graph through docs
- Leverages doctrine compliance for reliable introspection
- Affects all solution documentation structure
Implementation Reference
Context
Julee documentation exists in parallel forms: hand-written RST and autodoc-generated API docs. This creates drift, duplication, and maintenance burden.
The doctrine system establishes that tests ARE the specification. The same principle applies: docstrings ARE the documentation.
The Decision
Framework = Information Architecture, Content = Solution - julee provides semantic scaffolding; solutions provide content
Viewpoints Are Projections - Framework BCs (core, hcd, c4) become documentation viewpoints projecting solution content
Bespoke Templates Per Entity Type - Autodoc with entity-specific templates selected by doctrine-guaranteed structure
Directives Wrap Use Cases -
list-storieswrapsListStoriesUseCaseCode Exists → Autodoc; Code Doesn't Exist → Design Doc - Hand-written RST only for unimplemented features
Why an ADR?
This decision:
Implementation Reference
docs/ADRs/006-code-outward-documentation.md