Skill.re
AI for Code Documentation and Knowledge Bases
A Knowledge Base Pays for Itself
Your on-call engineer gets paged at 2am. "Payment processing is slow." They don't know your system. They page a senior engineer. Senior engineer spends 30 minutes on the call helping debug. It's a known issue with a known fix that's been explained five times before. You've just burned 30 minutes of senior engineer sleep and time.
Here's what happens at teams with a good knowledge base: Paged engineer checks the KB. Finds "Payment Processing Slow?" Gets the diagnosis steps. Finds the issue in 10 minutes. Applies the fix. Done. No escalation needed.
Every time someone asks the same question twice, that's a symptom: "This information should be documented." Good knowledge bases capture institutional knowledge so it doesn't have to be rediscovered constantly and doesn't walk out the door when people leave.
The challenge: building and maintaining comprehensive knowledge bases is tedious and often feels less urgent than shipping features. So most teams skip it. But the cost, in repeated explanations, onboarding friction, incident resolution time, compounds constantly.
AI doesn't solve the core problem (that you have to care about documentation), but it makes building and maintaining a knowledge base practical instead of aspirational.
What AI is Actually Good At
- Extracting documentation from code: "Here's a module. What should the docs say?" AI reads code and generates descriptions.
- Creating FAQ from questions: "Here are 20 questions our team has asked. Create an FAQ." AI extracts themes and answers.
- Generating structure and outlines: "What should our documentation look like?" AI suggests a structure.
- Updating docs when code changes: "We refactored this. Update the documentation." AI updates the docs to match new code.
- Identifying documentation gaps: "Here's our code. What's missing from the docs?" AI identifies what's undocumented.
- Creating examples: "Document how to use this API. Add working examples." AI generates realistic examples.
- Cross-linking and navigation: "This doc mentions X. Link to the X documentation." AI creates helpful connections.
- Creating multiple versions for different audiences: "Document this for engineers and for support. Different level of detail." AI writes versions tailored to audience.
Structuring Your Knowledge Base
Before you create documentation, decide what kind of knowledge base you need. Different structures for different purposes.
For Engineering (How Things Work):
- Architecture overview (systems, how they interact)
- Module documentation (what each piece does, how to use it)
- Patterns and conventions (how we do things)
- Troubleshooting guides (when things break, how to fix)
- API documentation (endpoints, parameters, examples)
- Deployment and operations (how to run the system)
For Onboarding (Getting New People Up to Speed):
- First week guide (what to do day 1, day 2, etc.)
- Tech stack overview (languages, frameworks, tools)
- Development environment setup (how to get a working local setup)
- Running your first task (walkthrough of a simple task)
- Getting help (who to ask for what)
- Common gotchas (things that trip up everyone)
For Support (Common Questions):
- Product FAQ (how to use the product)
- Troubleshooting (common problems and solutions)
- Integration guide (how to integrate with our system)
- Billing and account management
- Security and compliance (what we support)
For Operations (Running the System):
- Runbooks (how to respond to specific incidents)
- Deployment procedures (how to get code to production)
- Monitoring and alerting (what we watch, what we care about)
- Scaling and capacity (how to handle growth)
- Disaster recovery (what to do when everything breaks)
Generating Module Documentation
You have a critical module with no documentation. You could spend a day writing about it. Or you can spend 30 minutes guiding the AI.
Prompt:
Generate documentation for this module:
[PASTE CODE]
Documentation should include:
1. High-level: What does this module do? Why does it exist?
2. Key classes/functions: What's the main API? What do people use?
3. Usage examples: Show how to use it (both common cases and advanced)
4. Performance characteristics: Is it fast? Any scaling concerns?
5. Error handling: What errors can it throw? How should callers handle them?
6. Testing: How is it tested? What tests are important?
7. Known limitations: What doesn't it handle?
8. Future: What might change? What's planned?
Write for engineers who are new to the codebase.
Assume they know the language but not our patterns.
The AI generates structured documentation. You review it for accuracy. Add details it missed. Publish.
Real Example:
Your payment processor module: 500 lines of code, handles Stripe integration, retries, idempotency, webhooks. No documentation. AI generates:
Payment Processor Module
What It Does
Handles payment processing via Stripe with automatic retry, deduplication, and webhook verification. Ensures exactly-once semantics (no double charges) and comprehensive audit logging.
Key Components
- PaymentProcessor: Main class. Handles payment creation and processing.
- RetryQueue: Manages failed payments. Automatic exponential backoff.
- WebhookHandler: Receives Stripe webhooks. Verifies signatures. Updates payment status.
Usage Example
```
const payment = await processor.charge({
amount: 10000, // cents
currency: 'usd',
customerId: 'cust_123',
idempotencyKey: 'payment_unique_id',
metadata: { orderId: 'order_456' }
});
```
Performance
- Charges complete in 95%)
Integration tests: Use Stripe test cards (4242 for success, 4000 for decline)
Known Limitations
- Doesn't support ACH or international payments (yet)
- Retry logic is simple exponential backoff (no jitter)
- Doesn't handle currency conversion
Monitoring
Key metrics: /monitoring/payment-processor-metrics.js
Alert on: Failure rate >1%, 95th percentile latency >1.5s
Took 20 minutes to generate and review. Would have taken 2 hours to write manually. Done.
FAQ Generation from Real Questions
Your team gets asked the same questions constantly. Rather than explain repeatedly, document once.
Prompt:
Create a FAQ from these common questions we get asked:
- "How do I deploy a new feature?"
2. "What should I do if a deploy breaks something?"
3. "How do we version our API?"
4. "What's our database schema? Where do I find it?"
5. "How do I debug a failed payment?"
6. "What's the SLA for our API?"
7. "Can I break existing API clients when I ship a change?"
8. "How do I add a new environment variable?"
9. "What's our data retention policy?"
10. "How do I access production logs?"
For each question:
- Provide a clear, direct answer
- Include any relevant links or examples
- If it requires steps, list them clearly
- Mention who to contact if the answer doesn't solve the problem
Target audience: Backend engineers who are familiar with our codebase.
The AI generates a structured FAQ. You review, verify accuracy, add links. Publish. Now when someone asks "How do I deploy?" you point them to the FAQ instead of explaining again.
Onboarding Documentation That Actually Helps
New engineer arrives. They're productive after one week with great onboarding docs. They're lost after three weeks without them.
Prompt:
Create an onboarding guide for a backend engineer joining our team.
Context:
- Team size: 8 engineers (3 backend, 2 frontend, 1 infra, 2 product)
- Tech stack: Node.js 20, Express, PostgreSQL, Redis, AWS
- Company: B2B SaaS, payment processing focus, 500 customers
What they need to know:
1. Day 1: How to get code running locally
2. Days 1-2: Understanding our architecture
3. Week 1: Getting first contribution merged
4. Week 2-4: Building features on their own
5. Month 1+: Becoming productive
Include:
- Setup checklist (with troubleshooting)
- Glossary of internal terms
- How to ask questions (who to ask for what)
- Common gotchas (things that trip everyone up)
- How our deploy process works
- Who owns what
- Culture/practices (code review, testing, deployment cadence)
The AI generates a comprehensive guide. You customize it with your specific details (setup steps, team member names, etc.). New engineer gets onboarded 50% faster.
Making Documentation Maintainable
Documentation debt is worse than code debt because it silently gets more wrong. Code breaks loudly. Docs just become increasingly incorrect until no one trusts them.
Strategies to keep docs fresh:
1. Link Docs from Code
If code references a doc, link to it. "See /wiki/payment-processing for architecture." Dead links become obvious.
2. Document as You Change
New code? Add documentation. Refactor code? Update the docs. It takes 5 extra minutes then. You don't do it later.
3. Use AI to Update Docs When Code Changes
Prompt:
"We refactored our payment module. Here's the old code [OLD] and new code [NEW].
Update the documentation to match the new code."
AI updates docs faster than you manually would.
4. Quarterly Documentation Audit
Once per quarter, one engineer spends a day reviewing the knowledge base. Is it still accurate? What's outdated? What's missing? Fix it.
5. Track What's Read
Most docs tools show page views. If a doc has zero views in 3 months, either nobody needs it or nobody can find it. Either way, fix or remove it.
Documentation Culture: Make documentation part of how your team works. Include in code review: "Did you update the docs?" Include in onboarding: "Contributing to docs is as important as writing code." Include in performance reviews: "Did you help maintain our knowledge base?" Culture change is harder than tooling change, but it's what makes knowledge bases actually work.
Where to Host Your Knowledge Base
For Engineering (Code-focused):
- GitHub Wiki: Version control, linked to code. Limited formatting.
- GitHub Pages + Markdown: More powerful than wiki, still version controlled.
- MkDocs: Build searchable docs from markdown. Lightweight, good enough for most teams.
For General (Not code-specific):
- Notion: Easy to maintain, searchable, good for non-technical people too.
- Confluence: Enterprise-grade, integrations with JIRA, Slack. Overkill for small teams.
- GitBook: Beautiful docs, easy to update. Some limitations on customization.
Recommendation: Start with whatever platform you already use (GitHub, Notion, Confluence). Don't let tooling be the blocker. A good docs in Notion beats perfect docs in a fancy tool that nobody maintains.
Measuring Knowledge Base Health
Good signals:
- New engineers can get productive without constant help
- On-call engineers resolve incidents faster
- Repeated questions decrease over time
- People link to docs in PRs and Slack
- Documentation is updated when code changes
- Team members can find what they're looking for quickly
Bad signals:
- New engineers constantly asking "How do I...?"
- On-call engineers escalating issues that should be documented
- Same questions asked repeatedly
- Docs are outdated (referenced code no longer exists)
- Documentation is incomplete (missing critical systems)
- People use Slack history instead of looking at docs (because docs are hard to find or wrong)
Key Insight
Knowledge bases don't solve problems automatically. They only work if they're accurate, current, and discoverable. Use AI to make building and maintaining them practical. Make documentation part of your culture. The compounding benefit is enormous.
What to Do Monday Morning
- Choose a critical system with no documentation. Ask the AI to document it. Review and publish.
- Collect the top 10 questions your team gets asked. Ask the AI to create an FAQ.
- Create an onboarding document for your next new hire. Use AI to generate, then customize.
- Pick a platform (GitHub, Notion, Confluence). Create your knowledge base there. Start with 5 documents.
- Make a quarterly reminder to audit your docs. One engineer, one day, reviewing and updating.
Frequently Asked Questions
Q: How do we keep documentation from becoming outdated?
You can't prevent it, but you can manage it. Update docs when code changes (takes 5 minutes). Quarterly audits (find and fix big issues). Track what's read (remove orphaned docs). Make documentation part of your culture (it matters to your team, not an afterthought).
Q: What should we document and what shouldn't we?
Document: Critical systems, how things work, deployment procedures, common problems and solutions, API contracts. Don't document: Obvious code (if someone's reading the code, docs don't help), things that change weekly (too much maintenance overhead), internal implementation details that won't affect users.
Q: Can AI documentation be trusted?
AI generates structure and drafts. You verify accuracy, add context, fix errors. Treat AI docs like junior engineer's work: helpful starting point, but you review before publishing. Never publish AI-generated docs without verification.
Q: How do we make sure people actually use the knowledge base?
Make it easy to find. Link from code and Slack. Include in onboarding ("Check the KB first before asking"). In code review: "Did you update the KB?" This signals it's important.
Q: What if we have a lot of documentation already but it's outdated?
Use AI to help update it. "Here's our old documentation [OLD]. Here's our current code [NEW]. Update the docs to match reality." AI helps with the heavy lifting. You verify accuracy.
Implementation Case Study: From Chaos to Knowledge Base
A 50-person fintech startup had zero documentation. Onboarding new engineers took 6 weeks instead of 2. Support team spent 40% of time answering the same questions repeatedly. On-call incidents took 3x longer to resolve because engineers couldn't find the runbooks.
The Challenge: Building documentation from scratch felt impossible. The codebase was sprawling (15 services, 200K lines of code). No one wanted to spend weeks writing docs.
The Approach:
Month 1: Knowledge Extraction
They used AI strategically, not as a complete replacement. For each service, they asked an AI: "Read this service code and generate documentation structure." The AI produced outlines. The engineer who owned that service spent 2 hours fleshing out the outline with details, examples, and context. Result: in one month, 15 service overviews with examples were written (normally would take 2-3 months).
Month 2: FAQ Generation
They collected questions from their Slack backlog (last 3 months of #help channel). They grouped them by topic: "How do I deploy?", "How do I debug X?", "Why is Y slow?" etc. They asked AI to generate FAQ answers using their codebase as context. Each answer was reviewed by an engineer and fact-checked. Result: 40-question FAQ that covered 70% of recurring questions.
Month 3: Onboarding Guide
They asked AI: "Create a 4-week onboarding guide for a backend engineer joining fintech startup. First week covers setup and architecture. Week 2 covers their first PR. Week 3-4 covers building independent." They customized the guide with their specific details (their tech stack, team members, code review standards). New hires reported 50% faster productivity ramp.
Month 4: Runbooks for Oncall
For their top 15 incidents (things on-call engineers get paged about), they created AI-assisted runbooks. For each incident type, they asked: "Create a runbook for X. Include: symptoms, diagnosis steps, common fixes, escalation path, who to contact." Result: on-call incident resolution time dropped 40% (engineers could follow the runbook instead of asking senior engineers).
Results After 4 Months:
- Onboarding time: 6 weeks down to 3 weeks (50% faster productivity ramp)
- Support team time on FAQ questions: 40% down to 15% (AI FAQ answers most common questions)
- Incident resolution time: 60 min down to 36 min average (runbooks help)
- Knowledge retention: when people left the company, their knowledge wasn't lost (it was documented)
- Investment: ~400 hours of engineering time + AI tool cost ($2K/month) = $50K total
- ROI: In one year, the improved onboarding alone saved: 4 engineers × 2 weeks faster onboarding × 4 hires = 8 weeks of engineering time = $40K. Incident resolution savings were another $20K. Plus less attrition from better knowledge culture. ROI positive in year 1.
Ongoing Maintenance (Month 5+):
They made documentation a shared responsibility. Code review check: "Did you update the docs?" On-call runbook: "Did you update the runbook?" Quarterly audit: one engineer per quarter does a 2-day documentation review. It's not perfect, but it's living and maintained.
Advanced Patterns: Going Deeper
Pattern 1: Embedding Knowledge in Code
Instead of separate documentation, keep documentation close to code. Docstrings in every function. Architecture comments in key modules. Decision records (ADRs) in the git repo. This forces documentation to stay in sync because it's part of the code review process. Then use AI to generate higher-level documentation (guides, tutorials) from these lower-level artifacts.
Pattern 2: Searchable Knowledge Graph
Once you have documentation, make it discoverable. Use vector embeddings: convert docs to embeddings, then when engineers search, find semantically similar docs. "How do I debug payments?" should return payment-related docs even if the keyword "debug" doesn't appear. This dramatically improves knowledge discovery.
Pattern 3: Live Documentation with Code Examples
Documentation that's not tested gets outdated. Use tools like Doctest (Python) or similar to execute code examples in your documentation. If the code breaks, the example is obviously wrong and needs fixing. This forces docs to stay current.
Pattern 4: Documentation as a Product
For external documentation (APIs, SDKs), treat it like a product. Measure: are users finding what they need? Use analytics. Run surveys. Iterate based on feedback. A bad API is bearable if the docs are excellent. A great API is useless if the docs are cryptic.