Documentation Guidelines¶

This guide provides detailed instructions and best practices for creating high-quality technical designs. It covers section-by-section writing guidance, documentation compression best practices, phase planning examples, diagram standards, and a quick-reference checklist.

For the fill-in-the-blanks template, see: TD Template

Section-by-Section Writing Guidance¶

1. Summary¶

• Explain the problem and why now, the proposed direction at a glance, and expected impact.
• Keep to 1-3 short paragraphs.
• Call out scope level (e.g., internal-only, public API impacting, performance-sensitive).
• Add a brief "At a glance" list if helpful.

2. Context and Problem Statement¶

• Provide essential background, current behavior, pain points, and why existing approaches are insufficient.
• Link to prior work; avoid duplicating detailed content.
• Keep focused on the problem; defer solution details to sections 3 and 4.

2.1 Goals¶

• Define concrete, verifiable outcomes the design must achieve.
• Focus on user-observable improvements, maintainability gains, or risk reductions.
• Make goals specific, measurable, and unambiguous.
• Frame as outcomes rather than implementation details.

2.2 Out of Scope¶

• Prevent scope creep by explicitly stating what will not be addressed.
• List items that are explicitly excluded even if related to the topic.
• Include items stakeholders might assume are in scope.
• Explain briefly why certain items are out of scope when not obvious.

2.3 Assumptions and Constraints¶

• Document environmental factors and assumptions that shape the design.
• Include compatibility requirements, target runtimes/versions, performance bounds.
• Clearly distinguish assumptions (may be proven wrong) from hard constraints (must hold).
• Consider security, compliance, and operational requirements.

3. Design Overview¶

• High-level explanation of the approach and its building blocks. Keep this readable before diving into details.
• Provide a narrative of how the parts fit together.
• Reference detailed sections (e.g., "see section 4.2 for API").

3.1 Key Components¶

• Provide a quick map of major components and their responsibilities.
• Keep component names consistent with section 4.
• Use a table format for easy scanning and reference.

3.2 Architecture¶

• Use mermaid.js for diagrams.
• Keep diagrams simple and focused.
• Reference diagram elements in the text.

3.3 Interface Impact (Before / After)¶

• Make migrations explicit with direct mappings.
• Use a table; keep entries precise and user-actionable.
• If there is no API impact, state "None."

3.4 Removal/Deprecation Policy¶

• Clarify how changes ship and how consumers should migrate.
• Be explicit about timelines (e.g., alpha: no deprecation period).
• Note whether tests/examples will be updated in the same PRs.

4. Implementation Details¶

• Precisely specify technical implementation and configuration.
• Organize subsections by logical area.
• Include configuration formats, command signatures, and integration points.
• Document behavior, defaults, and error handling.
• Make examples copy-pastable for easy reference.

4.1 Core Contracts and APIs¶

• Define abstract interfaces and protocols.
• Include type hints and docstrings.
• Define error hierarchies.
• Keep implementation details minimal.

4.2 Component Architecture¶

• Describe how components are organized and interact.
• Explain data flow and responsibility boundaries.
• Use dependency diagrams when helpful.

4.3 Integration Points¶

• Specify how this design integrates with existing systems.
• List required external services/libraries.
• Document API contracts.

4.4 Error Handling and Edge Cases¶

• Document failure modes and recovery strategies.
• Define error hierarchy.
• Document retry strategies.

4.5 Observability¶

• Define what metrics and logs are emitted.
• List key metrics and their meaning.
• Document log levels and formats.
• Explain alerting thresholds.

5. Semantics¶

• Explain important behavioral aspects that span multiple APIs.
• Cover parameter ordering conventions.
• Explain error handling strategies.
• Document threading/async behavior if relevant.

6. Examples¶

• Demonstrate common usage patterns with concrete code.
• Keep examples focused and minimal.
• Ensure examples compile against the final API.
• Include at least 3 realistic examples covering basic usage, advanced patterns, and integration scenarios.

7. Test Matrix¶

• Define comprehensive test coverage strategy for the implementation.
• Organize tests by category (unit, integration, regression).
• Specify test file organization and naming conventions.
• Define coverage requirements for each test category.

8. Acceptance Criteria¶

• Provide a checklist for verifying the implementation meets requirements.
• Make criteria specific and testable.
• Include functional and non-functional requirements.
• Use this during reviews to verify conformance.

9. Rollout and Migration¶

• Describe how changes will be deployed and how users should migrate.
• Include migration guides or examples.
• Identify potential friction points and mitigation strategies.

10. Risks and Mitigations¶

• Identify potential issues and how they will be addressed.
• Consider performance, compatibility, and security implications.
• Address both technical and adoption risks.

11. Progress¶

• Track implementation status.
• Update regularly during implementation.
• Include links to implementation PRs when available.

12. Changelog¶

• Document significant changes to the technical design.
• Focus on milestones: phase completions, API changes, major removals.
• Format: **Date** — Milestone: key accomplishment 1, accomplishment 2

13. Glossary¶

• Define key terms used throughout the document.
• Include domain-specific terms and abbreviations.
• Keep definitions concise and clear.

Documentation Compression Best Practices¶

Based on real-world TD experience (e.g., TD-028 reduced 1,223 to 431 lines, 64.8% reduction), the following practices enable concise, readable technical designs without sacrificing clarity.

Architecture Diagrams¶

• Limit to 5-6 key components; avoid nested subgraphs.
• Use left-to-right flow (graph LR) for linear pipelines.
• Dark mode colors: fill:none, stroke:#color, color:#color.
• Reference diagram elements explicitly in text.

Code Examples and Implementation Details¶

Contract-First Approach:

• Show interface/protocol signatures completely.
• Hide full implementations with: "See source for implementation details."
• Use ... for method bodies in example protocols.
• Keep dataclass field definitions complete (external consumers need them).

Rationale: Design documents specify the public contract. Implementation details in source code do not belong in design docs and create maintenance burden.

Section Hierarchy and Organization¶

Numbering: Use 2-tier (4.1, 4.2, 4.3) not 3+ tier (4.1.1, 4.1.1.1); avoids deep nesting and improves navigation.

Section Responsibility:

• Section 3 (Design Overview): Source of truth for interfaces, contracts, before/after mappings.
• Section 4 (Implementation Details): State management, patterns, integration points.
• Cross-reference, do not duplicate: If explaining a protocol, refer back to section 3 instead of re-explaining.

Reference Material Organization¶

Use Tables for Metrics/Properties:

• One row per item (not grouped categories).
• Columns: Name | Type | Purpose or Term | Definition.
• Scans faster than narrative prose; enables quick lookup.

Lists vs. Prose¶

Use Lists For:

• Acceptance criteria (one per line with status indicator).
• Rollout phase deliverables.
• Test categories and coverage requirements.

Examples: Keep Minimal¶

• Target 5-10 lines per code block maximum.
• Structure: **Use case:** [prose] [code block]
• Multiple short examples are better than one long example.

Test Matrix Compression¶

Options:

1. Prose summary: "Unit (10 tests): auto-create parents, aggregation, snapshots. Integration (8 tests): hierarchical rollup, concurrent access. Regression (3 tests): error resilience."
2. Representative examples with ellipsis: "Unit: auto-create, aggregation, edge cases, ... (7 more)"
3. Category-based: Organize by Unit/Integration/Regression; remove individual checkmarks.

Changelog Conciseness¶

• Focus on milestones: phase completions, API changes, major removals only.
• Format: **Date** — Milestone: key accomplishment 1, accomplishment 2
• Avoid detailed task-by-task lists; readers reference the design itself for details.

Phase Planning Examples¶

Phase Structure Guidelines¶

• 3-6 phases total — More phases increase overhead, fewer phases lack clarity.
• Clear outcomes per phase — Each phase should deliver tangible value.
• Minimal change scope — Keep changes focused and testable.
• Targeted naming — Use descriptive phase names (e.g., "Core Infrastructure", "Integration Testing").

Examples from Successful TDs¶

TD-020 (6 phases):

1. Runtime Foundations — BootstrapRuntime, BootstrapPlan, DependencyAnalyzer
2. Container Internal Refactoring — _CoreContainer, DiContainerItem, DependencyGraph
3. Helper Component Extraction — RegistrationValidator, ServiceResolver, DependencyTracker
4. Container API Updates — Idempotent registrations, prepare(), metrics
5. Integration Adoption — ApplicationBootstrap, annotation processing
6. Documentation and Cleanup — User guides, API references, deprecation removal

TD-013 (4 phases):

1. Core Infrastructure — RegistrationRule protocol, BootstrapPlanBuilder
2. Built-in Rules — ServiceAnnotationRule, ComponentAnnotationRule
3. Integration and Testing — BootstrapRuntime integration, performance testing
4. Component Removal — Remove deprecated AnnotationProcessor

TD-012 (3 phases):

1. Core Annotation Definitions — @service, @component decorators
2. Processor + Injector Bridge — AnnotationProcessor, InjectorBridge
3. Scanning Hand-off — Registry contract for TD-013

Phase Structure Template¶

**Phase X**: <Phase name>
- <Specific, targeted task 1>
- <Specific, targeted task 2>
- <Clear outcome for this phase>

Diagram Standards¶

Mermaid.js Conventions¶

• Use mermaid.js for all diagrams for consistency.
• Keep diagrams simple and focused.
• Reference diagram elements in text.
• Update diagrams when design changes.

Color Palette¶

Use the following standardized color palette for consistent visual representation:

Dark Mode Styling¶

graph TB
    A[Component A] --> B[Component B]

    classDef success fill:none,stroke:#43A047,stroke-width:2px,color:#43A047
    classDef active fill:none,stroke:#1976D2,stroke-width:2px,color:#1976D2
    classDef infrastructure fill:none,stroke:#00C853,stroke-width:2px,color:#00C853

    class A active
    class B success

Quick-Reference Checklist for TD Authors¶

When writing a new technical design, use this checklist to ensure effective communication and conciseness:

• Diagrams simplified? 5-6 components max, dark mode colors, explicit references
• Code examples contract-first? Show interfaces fully, hide implementations with "See source"
• Sections non-duplicating? Section 3 is source of truth; section 4 cross-references instead of re-explaining
• Reference material as tables? One row per metric/term with Name | Type | Purpose columns
• Lists instead of prose? Acceptance criteria, deliverables, test categories all bulleted
• Examples concise? 5-10 lines max per code block; multiple short examples
• Test matrix compressed? Category-based prose summary, no individual checkmarks
• Changelog milestone-focused? Major phases, API changes, removals only

Example Quality Standards¶

Minimum Requirements¶

• 3+ realistic examples covering different usage patterns
• Basic usage — Simple, straightforward case
• Advanced patterns — Complex scenarios and edge cases
• Integration examples — How components work together

Example Quality Checklist¶

• Examples are conceptually correct
• Code follows project best practices
• Type hints are comprehensive
• Error handling is demonstrated
• Integration with other systems is shown
• Examples are copy-pastable (with proper imports)

Writing High-Quality Implementation Sections¶

Focus on Contracts, Not Implementation:

• Define abstract interfaces and protocols.
• Specify type signatures and behavior.
• Document error hierarchies and semantics.
• Avoid concrete implementation details that may change.

Code Quality Standards:

• Use proper docstring formats.
• Include comprehensive type hints.
• Follow project naming conventions.
• Use realistic but minimal code examples.

Risk Assessment Guidance¶

Comprehensive Risk Coverage:

• Technical risks — Performance, compatibility, security
• Adoption risks — Migration complexity, learning curve
• Operational risks — Monitoring, maintenance, scaling
• Timeline risks — Dependencies, resource constraints

Risk Format:

| Risk                                                | Mitigation                                                                  |
|-----------------------------------------------------|-----------------------------------------------------------------------------|
| Performance degradation from new abstraction layers | Profile critical paths; maintain O(1) lookups via optimized data structures |
| Migration complexity for existing users             | Provide comprehensive migration guide with before/after examples            |

Product Documentation Guidelines¶

Product documentation lives in docs/content/product/ and follows a traceability chain: Vision → Personas → User Stories → PRDs → Roadmap → Technical Design.

When to Write Product Docs¶

• New persona: When user research reveals a user archetype not covered by existing personas
• New user stories: When planning a new service or major feature
• New PRD: When a feature is complex enough to need formal requirements beyond user stories
• Updates: When implementation reveals gaps in existing product docs

Persona Maintenance¶

• Review personas annually or when the target audience shifts
• Each persona must have a unique self-hosting reality and technical comfort level
• Use the Persona Template for new personas
• Reference personas by name in user stories and PRDs

User Story Conventions¶

• Follow the ID scheme US-{AREA}-{NNN} (e.g., US-GRO-001)
• One file per epic (service domain or cross-cutting theme)
• Every story must reference a persona and have acceptance criteria
• Use the User Story Template

PRD Conventions¶

• Follow the ID scheme PRD-NNN (e.g., PRD-001)
• One PRD per service domain
• Every functional requirement gets an FR-N ID for traceability
• Link to user stories, personas, roadmap items, and technical designs
• Use the PRD Template

Traceability Expectations¶

Every feature should be traceable through the full chain:

1. Persona — Who needs this?
2. User Story — What do they need and why?
3. PRD — What are the detailed requirements?
4. Roadmap — When do we build it?
5. TD/ADR — How do we build it?

Not every feature needs all levels — small changes may only need a user story, while large features should have full traceability.

This guide is maintained by the loryth contributors. Please update it when patterns or best practices evolve.