Documentation Explanation Methodology

Universal framework for efficiently discovering, interpreting, and explaining technical documentation across text files, code comments, diagrams, and test descriptions.

When to Use This Skill

• Explaining system architecture from multiple documentation sources
• Extracting design rationale and decisions from specifications
• Understanding how components integrate by cross-referencing docs and code
• Navigating large documentation sets to answer specific questions
• Synthesizing information from text docs + code + diagrams + tests
• Identifying documentation gaps or inconsistencies
• Teaching users how a system works based on available documentation

Documentation Discovery Framework

Document Type Taxonomy

Technical projects contain multiple documentation types serving different purposes:

| Type | Purpose | Common Locations | Triggering Questions | |------|---------|------------------|---------------------| | Architecture Specs | System design, component hierarchy | docs/architecture/, docs/design/ | "How does X work?", "What's the overall structure?" | | Implementation Guides | Coding patterns, best practices | docs/implementation/, module headers | "How to implement Y?", "What pattern to use?" | | API References | Interface definitions, contracts | docs/api/, interface files, header comments | "What parameters does X take?", "What does Y return?" | | Test Plans | Verification strategy, coverage | docs/testing/, test files, assertion comments | "What tests exist?", "Is X verified?" | | Debugging Guides | Known issues, troubleshooting | docs/debugging/, docs/known_issues/ | "Why is X failing?", "Known problems with Y?" | | Integration Guides | Cross-module interfaces | docs/integration/, glue logic | "How do X and Y connect?", "What's the data flow?" | | Design Rationale | Why decisions were made | Embedded in specs, commit messages | "Why was X designed this way?", "What tradeoffs?" | | Reference Docs | Standards, protocols, ISA | docs/reference/, external links | "What does instruction X do?", "Protocol requirements?" |

Discovery Strategies

Text Documentation Search

Filename patterns reveal content:

• *_spec.md, *_architecture.md → High-level design
• *_implementation.md, *_guide.md → How-to information
• *_test_plan.md, *_verification.md → Testing strategy
• *_api.md, *_reference.md → Interface definitions
• *_debug.md, *_issues.md, *_troubleshooting.md → Problem-solving
• README.md → Entry point, overview
• CHANGELOG.md, *_status.md → Implementation progress

Directory structure indicates organization:

• docs/ → Primary documentation
• docs/cpu/, docs/modules/ → Component-specific docs
• reference/ → External or upstream documentation
• Root-level .md files → Project-wide information

Content signatures identify purpose:

• "Design Intent", "Rationale", "Why this approach" → Design decisions
• "Mandatory", "Must", "Shall" → Requirements
• "Known Issue", "Workaround", "Bug" → Debugging information
• "Example", "Usage", "How to" → Implementation guidance
• Tables with addresses/opcodes → Reference material
• "Status: Complete", "TODO", "Pending" → Implementation progress
• "❌ Wrong / ✅ Correct" → Anti-patterns and best practices

Code-as-Documentation Search

Module/Class headers contain architectural information:

// Module: vexriscv_decoder
// Purpose: Instruction decode stage with hazard detection
// Inputs: 32-bit instruction, pipeline control signals
// Outputs: ALU control, register addresses, immediate values
// Design rationale: Single-cycle decode with bypass forwarding

Interface definitions document contracts:

interface axi4_lite_if(input logic clk);
    // Address Write Channel
    logic [31:0] awaddr;   // Write address
    logic        awvalid;  // Write address valid
    logic        awready;  // Write address ready (response from slave)
    // ...
endinterface

Function/Task signatures with docstrings:

def analyze_pipeline_stall(trace_data: list, cycle: int) -> StallReason:
    """Determine why pipeline stalled at specific cycle.
    
    Args:
        trace_data: List of cycle-by-cycle execution trace
        cycle: Cycle number to analyze
        
    Returns:
        StallReason enum indicating hazard type (DATA/CONTROL/MEMORY)
        
    Algorithm:
        1. Check for RAW hazards (read-after-write)
        2. Check for control flow changes (branch/jump)
        3. Check for memory access conflicts
    """

Inline comments explain non-obvious logic:

// Multi-cycle shift operation causes 8-cycle stall
// Must hold decode stage until shifter completes
assign decode_stall = shifter_busy && rs2_is_shift_count;

Assertion messages document expected behavior:

property p_axi_wdata_stable;
    @(posedge clk) (awvalid && !awready) |=> $stable(awaddr);
endproperty

assert property (p_axi_wdata_stable) else
    $error("AXI Protocol Violation: awaddr changed while awvalid held and awready=0");

Test descriptions explain verification intent:

// Test: Load-Use Hazard with Forwarding
// Scenario: LW x5, 0(x1)  followed by  ADD x6, x5, x7
// Expected: Pipeline stalls 1 cycle, then forwards MEM→EX
// Verification: Check stall signal asserted for exactly 1 cycle

Naming conventions as implicit documentation:

• fetch_pc_valid → PC output from fetch stage is valid
• decode_rs1_hazard → Register source 1 has data hazard
• mem_stage_stall_req → Memory stage requesting pipeline stall
• csr_mtvec_base → Machine trap vector base address (CSR)

Progressive Disclosure Approach

Don't read everything at once. Use progressive refinement:

1. Overview first: Read high-level architecture docs, README files
2. Narrow down: Identify which subsystem/module is relevant
3. Read specifics: Load detailed module documentation
4. Cross-reference: Validate understanding against code/tests
5. Synthesize: Combine multiple sources into coherent explanation

Example flow for "How does hazard detection work?":

1. Overview: docs/architecture.md → Identifies hazard unit module
2. Narrow: docs/cpu/hazard_unit.md → Detailed hazard logic
3. Code: Read hazard_unit.sv module header and key logic
4. Tests: Check tests/*_hazard_test.sv for test scenarios
5. Synthesize: Explain based on spec + implementation + verification

Multi-Source Synthesis Patterns

Combining Documentation Sources

Architecture question: "How does component X work?"

Sources to combine:

1. Text spec (design intent, requirements)
2. Module header (interface, I/O signals)
3. Implementation (actual logic, algorithms)
4. Diagrams (visual structure - see references/diagram-interpretation.md)
5. Tests (expected behavior, edge cases)
6. Known issues (limitations, gotchas)

Synthesis pattern:

[Component X] {purpose from spec}

Architecture:
- {Structure from spec + diagrams}
- {Key interfaces from code headers}

Implementation:
- {Algorithm/logic from spec + inline comments}
- {Data flow from code analysis}

Verification:
- {Test scenarios from test descriptions}
- {Edge cases from assertions}

Known limitations:
- {Issues from debugging docs}

Cross-Validation Techniques

Does code match specification?

Check for mismatches:

• Spec says "single-cycle operation" but code shows multi-cycle FSM
• Spec defines 5 pipeline stages but code implements 4
• Interface diagram shows signal ready but code uses rdy
• Test plan says "fully verified" but no tests exist in test directory

Identifying documentation gaps:

• Module implemented but no specification document
• Complex algorithm in code without explanation comments
• Test exists but no test plan documentation
• Interface signals without timing diagrams

Resolving inconsistencies:

1. Code is typically source of truth for "what exists"
2. Specs reveal "what was intended"
3. Tests show "what was verified"
4. Comments explain "why it works this way"

If conflict exists:

• Note the discrepancy in explanation
• Verify which source is more recent (git history, timestamps)
• Check if issue is documented in known_issues
• Recommend updating documentation

Explanation Templates

"How does X work?" Pattern

Question structure: User wants to understand a component's operation

Response template:

[Component X] performs {high-level purpose from spec}.

Architecture:
{Structure description from spec/diagrams}
Key components: {From architecture doc or block diagram}

Interface:
{Input/output signals from code header or interface definition}

Operation:
{Algorithm/behavior from spec + code + inline comments}
{Timing/sequence from timing diagrams or sequence diagrams}

Example:
{Concrete example from test descriptions or code comments}

Related components:
{Cross-references to interacting modules}

"Why was X designed this way?" Pattern

Question structure: User wants design rationale

Response template:

[Design decision X] was chosen because {extract from design rationale sections}.

Alternatives considered:
{From "Design Alternatives" sections or commit messages}

Tradeoffs:
Advantages: {Performance, simplicity, compatibility, etc.}
Disadvantages: {Limitations, complexity, resource cost}

Constraints:
{Requirements that drove the decision - from specs}

Implementation status:
{Current state from status docs - complete/partial/planned}

"How to integrate X with Y?" Pattern

Question structure: User wants to connect two components

Response template:

[Component X] connects to [Component Y] through {interface description}.

Interface signals:
{Signal list from interface definitions or glue logic}

Data flow:
{Sequence from X to Y, from sequence diagrams or code}

Configuration required:
{Setup steps from integration guides or test setup code}

Example integration:
{From existing integration code or test harnesses}

Common issues:
{From debugging docs or known issues}

"What tests exist for X?" Pattern

Question structure: User wants verification status

Response template:

[Component X] verification coverage:

Test inventory:
{List from test plan docs and actual test files}

Scenarios covered:
{Test descriptions from test plan and test file headers}

Coverage gaps:
{Unimplemented tests from test plan, or features without tests}

Assertions:
{Assertion descriptions from assertion modules}

Known issues:
{Bugs/limitations from debugging docs}

Test execution:
{How to run tests - from test infrastructure docs}

"Known issues with X?" Pattern

Question structure: User debugging or planning work

Response template:

[Component X] known issues:

Issue inventory:
{List from known_issues.md, bug_fixes_*.md, or issue tracking}

Symptoms:
{Observable behavior from debugging docs}

Root causes:
{Analysis from debugging docs or bug fix descriptions}

Workarounds:
{Temporary solutions from debugging guides}

Status:
{Fixed/open/wontfix from status docs or changelogs}

Related tests:
{Tests that catch or demonstrate the issue}

Documentation Quality Assessment

When explaining from documentation, note quality indicators:

High-quality documentation signs:

• ✅ Design rationale explained
• ✅ Diagrams match code structure
• ✅ Interface contracts clearly defined
• ✅ Code has explanatory comments
• ✅ Tests document expected behavior
• ✅ Known limitations documented
• ✅ Examples provided

Documentation gaps to flag:

• ❌ Complex logic without comments
• ❌ Inconsistency between spec and code
• ❌ Modules without specifications
• ❌ Interfaces without timing diagrams
• ❌ Features without test coverage
• ❌ Bugs without troubleshooting guides
• ❌ No design rationale for unusual choices

Best Practices

Efficient Navigation

1. Start broad, narrow down: Overview → subsystem → component → details
2. Use file structure: Directory hierarchy reveals organization
3. Follow cross-references: Docs link related information
4. Check timestamps: Recent docs more likely accurate
5. Validate with code: Code is source of truth for implementation
6. Look for patterns: Similar modules have similar documentation

Interpretation Strategies

1. Read abstracts first: Frontmatter, summaries, introductions
2. Skim for structure: Headings, bullet lists, diagrams
3. Focus on relevant sections: Don't read everything
4. Extract key concepts: Design decisions, interfaces, algorithms
5. Note assumptions: Requirements, constraints, dependencies
6. Identify status: Complete, partial, planned, deprecated

Explanation Construction

1. Match user's level: Adjust detail to question specificity
2. Structure clearly: Headings, lists, logical flow
3. Concrete examples: From tests, code, or diagrams
4. Cite sources: Reference specific docs/files/lines
5. Note gaps: Be honest about missing information
6. Cross-reference: Link related components/concepts
7. Visual aids: Reference diagrams (see references/diagram-interpretation.md)

Bilingual Content Handling

When documentation uses multiple languages:

1. Identify primary language: Usually code/comments are English, design rationale may be native language
2. Preserve technical terms: Keep signal names, module names as-is
3. Translate for clarity: Convert design rationale to user's preferred language
4. Note language mixing: Flag when critical info is in non-English sections
5. Respect author intent: Some terms better left in original language

Example (Japanese design doc with English code):

Design Intent (設計意図): Pipeline hazard detection must complete in single cycle
to avoid degrading clock frequency.

Implementation: 
logic decode_hazard = (ex_rd == decode_rs1) && ex_regwrite_valid;

Output explanation: "The hazard unit performs single-cycle detection to maintain clock frequency. It checks if the decode stage's source register matches the execute stage's destination register while that destination is being written."

Auto-Generated Content Recognition

Some documentation is machine-generated:

Indicators:

• "AUTO-GENERATED - DO NOT EDIT" headers
• Consistent formatting (tables, lists)
• Timestamps in headers
• Scripts referenced (generate_docs.py)

Handling:

• Treat as reference (opcodes, register maps, API lists)
• Don't suggest edits to these files
• Point users to source data (JSON, schemas) for changes
• Note that manual docs may override auto-generated content

Advanced Techniques

Documentation Mining

For large documentation sets, mine for specific information:

Keyword search patterns:

• Design decisions: (rationale|why|because|chose|decision|tradeoff)
• Requirements: (must|shall|mandatory|required|critical)
• Issues: (bug|issue|problem|workaround|limitation)
• Status: (complete|implemented|pending|todo|wip)
• Examples: (example|usage|scenario|sample)

Cross-referencing:

• Find all mentions of component X across docs
• Build connection map (which components interact)
• Identify documentation clusters (related topics)

Version/Status Indicators

Track implementation progress from docs:

• ✅ / [Done] / Status: Complete → Implemented and verified
• ⏳ / [WIP] / Status: In Progress → Partial implementation
• ❌ / [TODO] / Status: Planned → Not yet implemented
• ⚠️ / [Known Issue] / Status: Buggy → Implemented but problematic
• 🔧 / [Refactoring] / Status: Redesign → Being reworked

Diagram Integration

Diagrams provide visual documentation - see detailed interpretation guide: references/diagram-interpretation.md

Quick diagram types:

• Block diagrams → Component structure and connectivity
• Sequence diagrams → Temporal behavior and message flow
• State machines → Control flow and state transitions
• Timing diagrams → Cycle-accurate signal behavior
• Flowcharts → Algorithmic logic and decision trees

Common Pitfalls

❌ Reading everything before answering: Too slow, wastes tokens ✅ Progressive disclosure: Start broad, narrow down as needed

❌ Treating specs as absolute truth: May be outdated or incorrect ✅ Cross-validate: Check spec against code and tests

❌ Ignoring code comments: Often contain critical context ✅ Mine code-as-documentation: Headers, comments, assertions, tests

❌ Missing diagram information: Diagrams often clearest explanation ✅ Interpret visuals: Extract structure and flow from diagrams

❌ Not noting documentation gaps: User needs complete picture ✅ Flag inconsistencies: Note missing docs, conflicts, uncertainties

❌ Over-explaining obvious concepts: Wastes time and tokens ✅ Match detail to question: Answer what was asked

❌ Single-source answers: Incomplete understanding ✅ Synthesize sources: Text + code + diagrams + tests = complete picture

Summary

Effective documentation explanation requires:

1. Smart discovery: Use taxonomy and search patterns to find relevant docs quickly
2. Multi-source synthesis: Combine text, code, diagrams, and tests
3. Progressive disclosure: Start broad, narrow down as needed
4. Cross-validation: Check consistency across sources
5. Clear explanation: Structure responses with templates
6. Quality assessment: Note gaps and inconsistencies
7. Efficient navigation: Don't read everything, focus on relevance

For diagram interpretation strategies, see references/diagram-interpretation.md.