Skip to content
HeliosDB HeliosDB Full

Process 6: Documentation Update & Link Validation

Process 6: Documentation Update & Link Validation

Part of: Feature Development Protocol

Overview

Trigger: Feature implementation complete (code merged) Owner: Engineering Lead + Technical Writer Timeline: Within 2 days of feature completion

Step 6A: Update Documentation (1 day)

Required Documentation Updates

  1. Update docs/FEATURES.md

    • Add new feature to appropriate category
    • Include description, use cases, examples

  2. Update docs/USER_GUIDE_INDEX.md

    • Add guide link (create guide if doesn’t exist)
    • Update table of contents

  3. Update docs/ROADMAP.md

    • Mark feature as Complete
    • Update implementation percentage

  4. Create Feature Guide (if major feature):

    • File: docs/guides/features/[FEATURE_NAME].md
    • Include: Overview, setup, examples, API reference, troubleshooting

  5. Update API Documentation:

    • Add new endpoints/functions to docs/api/
    • Update OpenAPI/Swagger specs if applicable

Checklist

  • docs/FEATURES.md updated
  • docs/USER_GUIDE_INDEX.md updated with guide link
  • docs/ROADMAP.md status updated
  • Feature guide created (or updated)
  • API documentation updated
  • Code examples tested and working

Run markdown link checker on all modified files:

Terminal window
# Install markdown-link-check (if not installed)
npm install -g markdown-link-check


# Check all markdown files
find docs -name "*.md" -exec markdown-link-check {} \;


# Or use find + custom script
./scripts/check-broken-links.sh

Manual Verification

  • Verify all cross-references work
  • Check that new feature links are bidirectional
  • Ensure images/diagrams load correctly
  1. Broken internal links: [text](docs/missing.md) → File doesn’t exist
  2. Incorrect relative paths: [text](../wrong/path.md) → Path incorrect
  3. Missing anchors: [text](file.md#missing-section) → Anchor doesn’t exist
  4. Outdated URLs: External links that have moved (HTTP 404)
  • Use relative paths for internal docs: [Guide](../guides/feature.md)
  • Use absolute GitHub paths for README: [Guide](docs/guides/feature.md)
  • Always include .md extension for markdown files
  • Use lowercase filenames with hyphens: my-feature-guide.md

Checklist

  • Markdown link checker run on all modified files
  • All broken links fixed
  • Cross-references verified bidirectional
  • Image paths validated
  • External URLs checked (return 200 OK)
  • Link consistency standards followed

Step 6C: Create Release Report (1 day)

Release Report Template

File: docs/releases/[VERSION]/[FEATURE_ID]_IMPLEMENTATION_REPORT.md

# [Feature Name] Implementation Report
**Version**: [Version]
**Feature ID**: [ID]
**Date**: [Date]
**Status**:  Complete | ⚠ Partial | 🚧 In Progress


## Summary
[1-paragraph overview]


## Implementation Details
### Architecture
[Diagrams, design decisions]


### Code Changes
- **Packages Modified**: [List]
- **Lines of Code**: [Count]
- **Tests Added**: [Count]


### Performance Results
[Benchmarks vs. targets]


## Challenges and Solutions
[Key engineering challenges encountered]


## Next Steps
[Follow-up work, production hardening]


## IP Status
- **Patent Filed**: [Yes/No - link to disclosure]
- **Defensive Publication**: [Yes/No - link to publication]
- **Trade Secret**: [Yes/No - see register]


## Series A Impact
- **ONE_PAGER.md**: [Updated  | N/A]
- **PITCH_DECK.md**: [Updated  | N/A]

File Organization

docs/releases/
├── v3.x/           # v3.0-v3.4 reports
├── v4.0/           # v4.0 reports
├── v5.0-v5.4/      # v5.x reports
├── v5.5/           # v5.5 reports (future)
└── v6.0/           # v6.0 reports (future)

Checklist

  • Implementation report created in correct version folder
  • Report includes IP status section
  • Performance benchmarks documented
  • Series A materials update confirmed

Navigation: ← Previous: Process 5 | Back to Index | Next: Enforcement →