Technical Documentation: RAG for Developers

Technical documentation is the lifeblood of development teams. APIs, integration guides, architecture docs, runbooks, ADRs... These critical resources are often scattered, hard to navigate, and quickly become outdated. A RAG assistant transforms this documentation into an intelligent copilot capable of answering developer questions in real-time, dramatically reducing the time lost searching for information.

The Challenge of Technical Documentation

Symptoms of Dysfunctional Documentation

Every technical team knows these daily frustrations:

• "The docs are outdated, we don't know what's current anymore"
• "I don't know where to start integrating this API"
• "The README doesn't answer my specific question"
• "New developers are lost during onboarding"
• "We documented this somewhere, but can't find where"

The Hidden Cost of Information Search

A McKinsey study reveals that developers spend an average of 20% of their time searching for information. For a team of 10 developers at $80k/year:

20% x 10 x $80,000 = $160,000/year lost to searching

And this figure doesn't include the cost of errors due to misunderstood or outdated documentation.

Technical Documentation Specificities

Technical Documentation RAG Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    Documentation Sources                         │
├─────────────────────────────────────────────────────────────────┤
│  OpenAPI    Markdown     Code        ADRs        Wiki           │
│  Specs      Docs         Comments    Records     Pages          │
│    │           │            │           │           │            │
│    └───────────┼────────────┼───────────┼───────────┘            │
│                ▼                                                 │
│        ┌───────────────┐                                         │
│        │  Doc Parser   │  ← Specialized parsers per format      │
│        └───────┬───────┘                                         │
└────────────────┼────────────────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Indexing Pipeline                             │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────┐     │
│  │  Semantic    │  │  Metadata    │  │     Embedding      │     │
│  │  Chunking    │──│  Extraction  │──│    (BGE-M3)        │     │
│  │              │  │              │  │                    │     │
│  └──────────────┘  └──────────────┘  └─────────┬──────────┘     │
│                                                 │                │
│                                                 ▼                │
│                                      ┌──────────────────┐       │
│                                      │  Vector Store    │       │
│                                      │   (Qdrant)       │       │
│                                      └──────────────────┘       │
└─────────────────────────────────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Access Interfaces                             │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────────────┐     │
│  │  Web    │  │  Slack  │  │  IDE    │  │     CLI         │     │
│  │  Chat   │  │  Bot    │  │ Plugin  │  │   (ailog ask)   │     │
│  └─────────┘  └─────────┘  └─────────┘  └─────────────────┘     │
└─────────────────────────────────────────────────────────────────┘

Multi-Source Indexing

Technical Documentation Connector

DEVELOPERpython
from pathlib import Path
from typing import List, Dict, Optional
import yaml
import re
from dataclasses import dataclass

@dataclass
class TechDocument:
    """Indexable technical document."""
    id: str
    title: str
    content: str
    doc_type: str
    source_path: str
    metadata: Dict

class TechDocIndexer:
    """Multi-source indexer for technical documentation."""

    def __init__(self, vector_db, embedding_model):
        self.vector_db = vector_db
        self.embedding_model = embedding_model
        self.parsers = {
            "openapi": self._parse_openapi,
            "markdown": self._parse_markdown,
            "python": self._parse_python_docstrings,
            "adr": self._parse_adr,
        }

    async def index_all_sources(self, config: Dict) -> int:
        """Index all configured documentation sources."""
        documents = []

        # API Documentation (OpenAPI/Swagger)
        if "openapi" in config:
            for spec_path in config["openapi"]:
                api_docs = await self._parse_openapi(spec_path)
                documents.extend(api_docs)
                print(f"Indexed {len(api_docs)} endpoints from {spec_path}")

        # Markdown Documentation
        if "markdown_dirs" in config:
            for doc_dir in config["markdown_dirs"]:
                md_docs = await self._parse_markdown_folder(doc_dir)
                documents.extend(md_docs)
                print(f"Indexed {len(md_docs)} markdown files from {doc_dir}")

        # Code Documentation (Docstrings)
        if "code_dirs" in config:
            for code_dir in config["code_dirs"]:
                code_docs = await self._parse_code_folder(code_dir)
                documents.extend(code_docs)
                print(f"Indexed {len(code_docs)} code docs from {code_dir}")

        # Architecture Decision Records
        if "adr_dir" in config:
            adr_docs = await self._parse_adr_folder(config["adr_dir"])
            documents.extend(adr_docs)
            print(f"Indexed {len(adr_docs)} ADRs")

        # Generate embeddings and store
        await self._store_documents(documents)

        return len(documents)

    async def _parse_openapi(self, spec_path: str) -> List[TechDocument]:
        """Parse an OpenAPI/Swagger specification."""
        with open(spec_path) as f:
            spec = yaml.safe_load(f)

        documents = []
        base_url = spec.get("servers", [{}])[0].get("url", "")

        for path, methods in spec.get("paths", {}).items():
            for method, details in methods.items():
                if method in ["get", "post", "put", "patch", "delete"]:
                    # Build enriched content
                    content = self._format_endpoint_doc(
                        method=method,
                        path=path,
                        details=details,
                        base_url=base_url
                    )

                    documents.append(TechDocument(
                        id=f"api_{method}_{path.replace('/', '_')}",
                        title=f"{method.upper()} {path}",
                        content=content,
                        doc_type="api_endpoint",
                        source_path=spec_path,
                        metadata={
                            "method": method.upper(),
                            "path": path,
                            "tags": details.get("tags", []),
                            "deprecated": details.get("deprecated", False),
                            "auth_required": self._requires_auth(details),
                        }
                    ))

        return documents

    def _format_endpoint_doc(
        self,
        method: str,
        path: str,
        details: Dict,
        base_url: str
    ) -> str:
        """Format endpoint documentation for indexing."""
        sections = []

        # Header
        sections.append(f"# {method.upper()} {path}")
        sections.append(f"Full URL: {base_url}{path}")

        # Description
        if details.get("summary"):
            sections.append(f"\n## Summary\n{details['summary']}")
        if details.get("description"):
            sections.append(f"\n## Description\n{details['description']}")

        # Parameters
        params = details.get("parameters", [])
        if params:
            sections.append("\n## Parameters")
            for param in params:
                required = "required" if param.get("required") else "optional"
                param_type = param.get("schema", {}).get("type", "any")
                sections.append(
                    f"- **{param['name']}** ({param['in']}, {param_type}, {required}): "
                    f"{param.get('description', 'Not documented')}"
                )

        # Request Body
        request_body = details.get("requestBody", {})
        if request_body:
            sections.append("\n## Request Body")
            content = request_body.get("content", {})
            for content_type, schema in content.items():
                sections.append(f"Content-Type: {content_type}")
                if "example" in schema:
                    sections.append(f"Example:\n```json\n{schema['example']}\n```")

        # Responses
        responses = details.get("responses", {})
        if responses:
            sections.append("\n## Responses")
            for code, response in responses.items():
                sections.append(f"- **{code}**: {response.get('description', '')}")

        return "\n".join(sections)

    def _requires_auth(self, details: Dict) -> bool:
        """Check if endpoint requires authentication."""
        return bool(details.get("security", []))

    async def _parse_markdown_folder(self, folder: str) -> List[TechDocument]:
        """Parse all Markdown files in a folder."""
        documents = []
        folder_path = Path(folder)

        for md_file in folder_path.rglob("*.md"):
            with open(md_file, encoding="utf-8") as f:
                content = f.read()

            # Extract YAML metadata if present
            metadata = {}
            if content.startswith("---"):
                try:
                    _, yaml_content, content = content.split("---", 2)
                    metadata = yaml.safe_load(yaml_content)
                except:
                    pass

            # Extract title
            title_match = re.search(r"^#\s+(.+)$", content, re.MULTILINE)
            title = title_match.group(1) if title_match else md_file.stem

            # Determine category from path
            relative_path = md_file.relative_to(folder_path)
            category = relative_path.parent.name if relative_path.parent.name != "." else "general"

            documents.append(TechDocument(
                id=f"doc_{md_file.stem}_{hash(str(md_file))}",
                title=title,
                content=content,
                doc_type="markdown",
                source_path=str(md_file),
                metadata={
                    "category": category,
                    "file_name": md_file.name,
                    **metadata
                }
            ))

        return documents

    async def _parse_code_folder(self, folder: str) -> List[TechDocument]:
        """Extract docstrings from Python files."""
        import ast
        documents = []
        folder_path = Path(folder)

        for py_file in folder_path.rglob("*.py"):
            try:
                with open(py_file, encoding="utf-8") as f:
                    source = f.read()

                tree = ast.parse(source)

                for node in ast.walk(tree):
                    # Classes
                    if isinstance(node, ast.ClassDef):
                        docstring = ast.get_docstring(node)
                        if docstring:
                            documents.append(TechDocument(
                                id=f"class_{py_file.stem}_{node.name}",
                                title=f"Class {node.name}",
                                content=f"# Class {node.name}\n\n{docstring}",
                                doc_type="code_class",
                                source_path=str(py_file),
                                metadata={
                                    "class_name": node.name,
                                    "line_number": node.lineno
                                }
                            ))

                    # Functions
                    elif isinstance(node, ast.FunctionDef):
                        docstring = ast.get_docstring(node)
                        if docstring and not node.name.startswith("_"):
                            # Extract signature
                            args = [arg.arg for arg in node.args.args]
                            signature = f"{node.name}({', '.join(args)})"

                            documents.append(TechDocument(
                                id=f"func_{py_file.stem}_{node.name}",
                                title=f"Function {node.name}",
                                content=f"# {signature}\n\n{docstring}",
                                doc_type="code_function",
                                source_path=str(py_file),
                                metadata={
                                    "function_name": node.name,
                                    "signature": signature,
                                    "line_number": node.lineno
                                }
                            ))

            except SyntaxError:
                continue  # Skip files with syntax errors

        return documents

    async def _parse_adr_folder(self, folder: str) -> List[TechDocument]:
        """Parse Architecture Decision Records."""
        documents = []
        folder_path = Path(folder)

        for adr_file in sorted(folder_path.glob("*.md")):
            with open(adr_file, encoding="utf-8") as f:
                content = f.read()

            # Extract ADR number and title
            adr_match = re.match(r"(\d+)-(.+)\.md", adr_file.name)
            if adr_match:
                adr_number = adr_match.group(1)
                adr_slug = adr_match.group(2)
            else:
                adr_number = "0"
                adr_slug = adr_file.stem

            # Extract status (Accepted, Deprecated, Superseded, etc.)
            status_match = re.search(r"Status:\s*(\w+)", content, re.IGNORECASE)
            status = status_match.group(1) if status_match else "Unknown"

            # Extract title
            title_match = re.search(r"^#\s+(.+)$", content, re.MULTILINE)
            title = title_match.group(1) if title_match else adr_slug.replace("-", " ")

            documents.append(TechDocument(
                id=f"adr_{adr_number}_{adr_slug}",
                title=f"ADR-{adr_number}: {title}",
                content=content,
                doc_type="adr",
                source_path=str(adr_file),
                metadata={
                    "adr_number": int(adr_number),
                    "status": status,
                    "slug": adr_slug
                }
            ))

        return documents

    async def _store_documents(self, documents: List[TechDocument]):
        """Generate embeddings and store in vector database."""
        for doc in documents:
            embedding = await self.embedding_model.embed(doc.content)

            await self.vector_db.upsert(
                collection="tech_docs",
                points=[{
                    "id": doc.id,
                    "vector": embedding,
                    "payload": {
                        "title": doc.title,
                        "content": doc.content,
                        "doc_type": doc.doc_type,
                        "source_path": doc.source_path,
                        **doc.metadata
                    }
                }]
            )

Developer-Focused System Prompt

DEVELOPERpython
TECH_DOC_SYSTEM_PROMPT = """You are an expert technical assistant for the development team.
You help developers quickly find information in technical documentation.

## Your expertise
- API Reference: endpoints, parameters, request examples
- Integration guides: step-by-step procedures
- Architecture: components, dependencies, data flows
- Code: functions, classes, usage patterns
- ADRs: context and justification for technical decisions

## Response rules
1. **Technical precision**: Be exact, cite specific versions and parameters
2. **Code examples**: Always include a working example when relevant
3. **Sources**: Systematically cite the source file or endpoint
4. **Conciseness**: Get to the point, developers have limited time
5. **Honesty**: If the info doesn't exist in the docs, say so clearly

## Response format

### For API questions

Endpoint: METHOD /path Auth: Required/Not required

Example: curl -X METHOD 'url' -H 'Header: value'

Response: {json_example}

Source: openapi.yaml

### For integration questions

Steps:

1. First step
2. Second step

Code: code_example

Source: docs/integration.md

## Available documentation
{context}

## Question
{query}
"""

Practical Use Cases

API Questions

Developer: "How do I create a user via the API?"

Assistant:

**Endpoint**: POST /api/v1/users
**Auth**: Bearer token required

**Request body**:
{
  "email": "[email protected]",
  "name": "John Doe",
  "role": "member"
}

**curl example**:
curl -X POST 'https://api.example.com/api/v1/users' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"email": "[email protected]", "name": "John Doe", "role": "member"}'

**Responses**:
- 201: User created successfully
- 400: Invalid data
- 409: Email already in use

Source: openapi.yaml (POST /api/v1/users)

Debugging and Errors

Developer: "What does the AUTH_TOKEN_EXPIRED error mean?"

Assistant:

**Error AUTH_TOKEN_EXPIRED**

This error occurs when the JWT token has exceeded its validity period (24h by default).

**Solutions**:
1. Refresh the token via POST /api/v1/auth/refresh
2. Request a new token via POST /api/v1/auth/login

**Error handling code**:
async function apiCall(endpoint) {
  try {
    return await fetch(endpoint, { headers: getAuthHeaders() });
  } catch (error) {
    if (error.code === 'AUTH_TOKEN_EXPIRED') {
      await refreshToken();
      return apiCall(endpoint);  // Retry
    }
    throw error;
  }
}

Sources: docs/authentication.md, errors/auth-errors.md

Architecture Questions

Developer: "How does the payment service communicate with the order service?"

Assistant:

**Communication Payment Service <-> Order Service**

The Payment Service communicates with the Order Service via an Event-Driven pattern:

┌─────────────┐    payment.completed    ┌─────────────┐
│   Payment   │ ────────────────────→   │    Order    │
│   Service   │                         │   Service   │
└─────────────┘                         └─────────────┘
       │                                       │
       │         RabbitMQ Exchange             │
       └───────────────┬───────────────────────┘
                       │
               payment.events

**Events emitted**:
- payment.initiated: Payment started
- payment.completed: Payment successful -> triggers order.confirm
- payment.failed: Failure -> triggers order.cancel

**Why this choice?** (ADR-015)
Service decoupling to enable independent scaling and fault resilience.

Sources: ADR-015, docs/architecture/event-flows.md

IDE Integration

VS Code Extension

DEVELOPERtypescript
import * as vscode from 'vscode';

interface AilogResponse {
    answer: string;
    sources: Array<{ path: string; title: string }>;
    confidence: number;
}

export function activate(context: vscode.ExtensionContext) {
    // Main command: ask a question
    const askCommand = vscode.commands.registerCommand(
        'ailog.askDoc',
        async () => {
            const question = await vscode.window.showInputBox({
                prompt: 'Ask your documentation question',
                placeHolder: 'How do I authenticate an API request?'
            });

            if (!question) return;

            // Get current context
            const editor = vscode.window.activeTextEditor;
            const context = {
                currentFile: editor?.document.fileName,
                selectedCode: editor?.document.getText(editor.selection),
                language: editor?.document.languageId
            };

            // Show response panel
            const panel = vscode.window.createWebviewPanel(
                'ailogResponse',
                'Ailog - Documentation',
                vscode.ViewColumn.Beside,
                { enableScripts: true }
            );

            panel.webview.html = getLoadingHtml();

            try {
                const response = await askAilog(question, context);
                panel.webview.html = formatResponseHtml(response);
            } catch (error) {
                panel.webview.html = getErrorHtml(error);
            }
        }
    );

    // Contextual command: explain selected code
    const explainCommand = vscode.commands.registerCommand(
        'ailog.explainCode',
        async () => {
            const editor = vscode.window.activeTextEditor;
            if (!editor) return;

            const selection = editor.selection;
            const selectedCode = editor.document.getText(selection);

            if (!selectedCode) {
                vscode.window.showWarningMessage('Select code to explain');
                return;
            }

            const question = `Explain this code and its usage in our codebase:\n\`\`\`\n${selectedCode}\n\`\`\``;
            const response = await askAilog(question, {
                currentFile: editor.document.fileName,
                language: editor.document.languageId
            });

            // Show inline or in panel
            showInlineResponse(editor, selection, response);
        }
    );

    context.subscriptions.push(askCommand, explainCommand);
}

async function askAilog(
    question: string,
    context: object
): Promise<AilogResponse> {
    const config = vscode.workspace.getConfiguration('ailog');
    const apiKey = config.get<string>('apiKey');
    const endpoint = config.get<string>('endpoint') || 'https://api.ailog.fr';

    const response = await fetch(`${endpoint}/v1/ask`, {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${apiKey}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({ question, context })
    });

    if (!response.ok) {
        throw new Error(`API Error: ${response.status}`);
    }

    return response.json();
}

JetBrains Plugin (IntelliJ, PyCharm)

DEVELOPERkotlin
// AilogToolWindowFactory.kt
class AilogToolWindowFactory : ToolWindowFactory {
    override fun createToolWindowContent(
        project: Project,
        toolWindow: ToolWindow
    ) {
        val panel = AilogPanel(project)
        val content = ContentFactory.getInstance()
            .createContent(panel, "Ailog Docs", false)
        toolWindow.contentManager.addContent(content)
    }
}

class AilogPanel(private val project: Project) : JPanel() {
    private val questionField = JTextField()
    private val responseArea = JEditorPane("text/html", "")

    init {
        layout = BorderLayout()

        // Question bar
        val inputPanel = JPanel(BorderLayout())
        inputPanel.add(JLabel("Question: "), BorderLayout.WEST)
        inputPanel.add(questionField, BorderLayout.CENTER)

        val askButton = JButton("Ask")
        askButton.addActionListener { askQuestion() }
        inputPanel.add(askButton, BorderLayout.EAST)

        add(inputPanel, BorderLayout.NORTH)
        add(JScrollPane(responseArea), BorderLayout.CENTER)

        // Keyboard shortcut
        questionField.addActionListener { askQuestion() }
    }

    private fun askQuestion() {
        val question = questionField.text
        if (question.isBlank()) return

        // Active file context
        val editor = FileEditorManager.getInstance(project).selectedTextEditor
        val context = mapOf(
            "file" to editor?.virtualFile?.path,
            "selection" to editor?.selectionModel?.selectedText
        )

        // Async call
        ApplicationManager.getApplication().executeOnPooledThread {
            val response = AilogClient.ask(question, context)

            SwingUtilities.invokeLater {
                responseArea.text = formatResponse(response)
            }
        }
    }
}

Continuous Synchronization

Git Webhook for Automatic Updates

DEVELOPERpython
from fastapi import FastAPI, Request, HTTPException
import hmac
import hashlib

app = FastAPI()

@app.post("/webhook/github")
async def github_webhook(request: Request):
    """GitHub webhook for documentation sync."""
    # Verify signature
    signature = request.headers.get("X-Hub-Signature-256")
    body = await request.body()

    if not verify_signature(body, signature):
        raise HTTPException(status_code=401, detail="Invalid signature")

    payload = await request.json()
    event = request.headers.get("X-GitHub-Event")

    if event == "push":
        # Check if doc files changed
        changed_files = []
        for commit in payload.get("commits", []):
            changed_files.extend(commit.get("added", []))
            changed_files.extend(commit.get("modified", []))

        doc_files = [f for f in changed_files if is_doc_file(f)]

        if doc_files:
            # Trigger reindexing
            await trigger_reindex(doc_files)
            return {"status": "reindex_triggered", "files": doc_files}

    return {"status": "ignored"}

def is_doc_file(path: str) -> bool:
    """Check if file is documentation."""
    doc_patterns = [
        "docs/",
        "README",
        ".md",
        "openapi",
        "swagger",
        "adr/"
    ]
    return any(pattern in path for pattern in doc_patterns)

async def trigger_reindex(files: list):
    """Trigger reindexing of modified files."""
    indexer = TechDocIndexer(vector_db, embedding_model)

    for file_path in files:
        if file_path.endswith(".md"):
            doc = await indexer._parse_markdown_file(file_path)
            await indexer._store_documents([doc])
        elif "openapi" in file_path or "swagger" in file_path:
            docs = await indexer._parse_openapi(file_path)
            await indexer._store_documents(docs)

    print(f"Reindexed {len(files)} documentation files")

Measuring Effectiveness

Key Metrics

Tracking Dashboard

DEVELOPERpython
class DocRAGAnalytics:
    """Analytics for measuring documentation RAG effectiveness."""

    def get_weekly_report(self) -> Dict:
        """Generate weekly report."""
        return {
            "total_queries": self.count_queries(days=7),
            "unique_users": self.count_unique_users(days=7),
            "avg_response_time_ms": self.avg_response_time(days=7),
            "satisfaction_rate": self.satisfaction_rate(days=7),
            "top_queries": self.top_queries(days=7, limit=10),
            "unanswered_queries": self.unanswered_queries(days=7),
            "most_used_docs": self.most_cited_sources(days=7, limit=10)
        }

Related Resources

• Enterprise Knowledge Base - Complete KB architecture guide
• Confluence + RAG - Team wiki integration
• Notion + RAG - Structured documentation
• Introduction to RAG - RAG fundamentals

---

Smart Documentation with Ailog

Make your technical documentation instantly accessible. Ailog offers:

• Multi-source indexing: OpenAPI, Markdown, code comments, ADRs
• IDE integration: VS Code and JetBrains extensions
• Automatic sync: Git webhooks for real-time updates
• Code-rich responses: Snippets and examples in answers
• European hosting: Native GDPR compliance

Your developers lose hours every week searching through docs. Give them an assistant that finds answers instantly.

Try Ailog for free | See documentation demo