← Back to Projects
📚
Docs
Keep internal docs in sync with code
Thesis
Internal docs are outdated or missing. AI can watch for changes and flag when docs need updates.
The Problem
Documentation is always out of date: Someone writes a README. The code changes. The README doesn't. Six months later, new developer follows the docs and everything breaks. "Oh yeah, we don't do it that way anymore." Nobody has time to update docs. So they rot. And onboarding suffers, bugs happen, knowledge lives only in people's heads.
Implementation Approaches
Approach 1
RecommendedGit Watcher + Flag System (Recommended)
Monitor code changes and flag docs that might be stale
⏱️2 weeks
📊Medium complexity
Implementation
- →GitHub/GitLab integration watches commits
- →Map docs to code sections they describe
- →AI detects: did this change affect related docs?
- →Flag docs for review with context
- →Suggest specific updates when possible
Pros
- +Proactive, catches staleness as it happens
- +Works with existing doc structure
- +Clear action items for doc updates
- +Flywheel: learns what changes matter for docs
Cons
- −Mapping docs to code is imperfect
- −May generate false positives
- −Requires docs to exist in the first place
Approach 2
Doc Generator from Code
Auto-generate documentation from codebase
⏱️2 weeks
📊High complexity
Implementation
- →Analyze codebase structure and patterns
- →Generate: architecture overview, API docs, setup guides
- →Keep in sync via regeneration on changes
- →Diff-based updates to preserve manual additions
Pros
- +Docs always match code by definition
- +Reduces manual documentation burden
- +Consistent format across projects
- +Can generate from scratch for undocumented code
Cons
- −Generated docs often lack context/reasoning
- −Quality depends on code quality
- −May overwrite valuable manual content
Approach 3
Knowledge Q&A Layer
Chatbot that answers code questions from docs + code
⏱️1 week
📊Low complexity
Implementation
- →Index docs and codebase
- →Developers ask questions in natural language
- →AI answers with sources
- →Track: what questions aren't covered?
Pros
- +Works even with incomplete docs
- +Surfaces what's actually needed
- +Lower bar than full doc maintenance
- +Shows gaps via unanswered questions
Cons
- −Doesn't fix underlying doc problem
- −RAG quality can be inconsistent
- −Developers might not ask
Validation Plan
Hypothesis to Test
Dev teams will pay $29/mo to keep docs in sync with code automatically
Validation Phases
1
Staleness Audit
1 week- •Audit docs in 3 active repos
- •Compare doc content to current code
- •Find: what's stale, what's missing
- •Estimate: how much time to fix manually
✓Find significant staleness in 3/3 repos
2
Watcher MVP
2 weeks- •Build GitHub integration
- •Implement doc-to-code mapping
- •Test staleness detection on real repos
- •Measure: true positive rate
✓Catch 80%+ of doc-affecting changes with < 20% false positives
3
Team Beta
2 weeks- •Deploy to 3 dev teams
- •Integrate with their doc workflow (Notion, Confluence)
- •Track: flags generated, flags acted on
- •Validate $29/mo pricing
✓Teams act on 50%+ of flags, want to continue
Kill Criteria
Stop and move on if any of these become true:
- ✕Too many false positives make it noisy
- ✕Doc-to-code mapping is too unreliable
- ✕Teams ignore flags, don't value doc currency
- ✕Competitive tools already do this well