Docs-as-Code Pipeline

Duration: 60 minutes Difficulty: Intermediate Pattern: Sequential Chain + Feedback Loop

This scenario demonstrates a documentation quality improvement pipeline using docs-as-code personas to structure, write, review, and automate documentation.

Scenario Overview

Problem: A project's documentation is scattered, inconsistent, and lacks API coverage. The documentation needs to be restructured, quality-scored, and set up for automated generation and validation.

Goal: Execute a four-persona documentation pipeline that produces a documentation architecture, content strategy, quality review, and API documentation with automation setup.

Persona Team

Persona	ID	Role	Category
Information Architect	IA	Designs documentation structure and taxonomy	docs_as_code
Content Strategist	CS	Plans content creation and maintenance strategy	docs_as_code
Documentation Quality Reviewer	DQR	Reviews and scores documentation quality	docs_as_code
API Documentation Specialist	ADS	Creates and validates API documentation	docs_as_code

Setup

from fcc.personas.registry import PersonaRegistry
from fcc.simulation.engine import SimulationEngine
from fcc.simulation.messages import SimulationMessage
from fcc.messaging.bus import EventBus
from fcc.messaging.events import Event, EventType

registry = PersonaRegistry.from_yaml_directory("src/fcc/data/personas")
bus = EventBus()
engine = SimulationEngine(registry=registry, mode="deterministic")

project_docs = {
    "name": "FCC Agent Team Framework",
    "current_pages": 85,
    "api_modules": 20,
    "known_gaps": [
        "No API reference for search module",
        "Federation module undocumented",
        "Tutorial coverage incomplete",
        "No contribution guide",
    ],
    "target_audience": ["developers", "data scientists", "team leads"],
}

Phase 1: Documentation Architecture

The Information Architect designs the documentation structure:

ia_message = SimulationMessage(
    sender="orchestrator",
    receiver="IA",
    content=(
        f"Design a documentation architecture for:\n"
        f"Project: {project_docs['name']}\n"
        f"Current pages: {project_docs['current_pages']}\n"
        f"API modules: {project_docs['api_modules']}\n"
        f"Known gaps: {', '.join(project_docs['known_gaps'])}\n"
        f"Audiences: {', '.join(project_docs['target_audience'])}\n\n"
        "Design:\n"
        "- Information hierarchy (top-level categories and subcategories)\n"
        "- Navigation taxonomy (sidebar structure)\n"
        "- Content type definitions (tutorial, guide, reference, explanation)\n"
        "- Cross-reference strategy between content types\n"
        "- URL structure and naming conventions\n"
        "Produce a documentation site map with all planned pages."
    ),
    phase="find",
)

doc_architecture = engine.step(ia_message)
print(f"Documentation Architecture: {len(doc_architecture.content)} chars")

Phase 2: Content Strategy

The Content Strategist plans content creation and maintenance:

cs_message = SimulationMessage(
    sender="IA",
    receiver="CS",
    content=(
        f"Create a content strategy based on this architecture:\n\n"
        f"{doc_architecture.content[:500]}\n\n"
        f"Target audiences: {', '.join(project_docs['target_audience'])}\n\n"
        "Plan:\n"
        "- Content priorities (which pages to create first)\n"
        "- Writing style guide (tone, voice, terminology)\n"
        "- Template specifications (frontmatter, headings, code blocks)\n"
        "- Content lifecycle (draft -> review -> publish -> update)\n"
        "- Audience-specific learning paths\n"
        "- Content reuse strategy (includes, snippets, shared components)\n"
        "Produce a content plan with priorities and timelines."
    ),
    phase="create",
)

content_strategy = engine.step(cs_message)
print(f"Content Strategy: {len(content_strategy.content)} chars")

Phase 3: Quality Review

The Documentation Quality Reviewer evaluates existing documentation:

dqr_message = SimulationMessage(
    sender="CS",
    receiver="DQR",
    content=(
        f"Review the documentation quality for: {project_docs['name']}\n\n"
        f"Architecture:\n{doc_architecture.content[:400]}\n\n"
        f"Content strategy:\n{content_strategy.content[:400]}\n\n"
        "Evaluate against quality dimensions:\n"
        "- Completeness: Are all modules documented?\n"
        "- Accuracy: Do examples match current API?\n"
        "- Clarity: Is the language accessible to target audiences?\n"
        "- Consistency: Do pages follow the style guide?\n"
        "- Navigation: Can users find what they need?\n"
        "- Code examples: Do they run without errors?\n\n"
        "Score each dimension 0-1 and provide specific improvement "
        "recommendations for each gap."
    ),
    phase="critique",
)

quality_review = engine.step(dqr_message)
print(f"Quality Review: {len(quality_review.content)} chars")

Quality Scoring

from fcc.collaboration.scoring import ScoringEngine

scorer = ScoringEngine()

doc_scores = {
    "architecture": scorer.score_text(doc_architecture.content),
    "content_strategy": scorer.score_text(content_strategy.content),
    "quality_review": scorer.score_text(quality_review.content),
}

print("\nDocumentation Quality Scores:")
for area, score in doc_scores.items():
    print(f"  {area}: {score:.2f}")

Phase 4: API Documentation

The API Documentation Specialist creates and validates API docs:

ads_message = SimulationMessage(
    sender="DQR",
    receiver="ADS",
    content=(
        f"Create API documentation for the undocumented modules:\n\n"
        f"Quality review findings:\n{quality_review.content[:400]}\n\n"
        "Generate API documentation for:\n"
        "- fcc.search (SearchIndex, PersonaSearchIndex, ActionSearchIndex)\n"
        "- fcc.federation (EntityResolver, NamespaceRegistry, ChangeTracker)\n"
        "- fcc.knowledge (KnowledgeGraph, builders, serializers)\n"
        "- fcc.rag (DocumentChunker, SemanticRetriever, RAGPipeline)\n\n"
        "For each module produce:\n"
        "- Module overview\n"
        "- Class reference with parameters and return types\n"
        "- Usage examples (runnable code blocks)\n"
        "- Integration with other FCC modules\n"
        "Follow the project's docs-as-code conventions."
    ),
    phase="create",
)

api_docs = engine.step(ads_message)
print(f"API Documentation: {len(api_docs.content)} chars")

Improvement Cycle

Apply a feedback loop to improve based on the quality review:

# Check if quality meets threshold
quality_threshold = 0.65
api_score = scorer.score_text(api_docs.content)
doc_scores["api_documentation"] = api_score

overall = sum(doc_scores.values()) / len(doc_scores)
print(f"\nOverall documentation score: {overall:.2f}")

if overall < quality_threshold:
    # Send back for improvement
    improvement_message = SimulationMessage(
        sender="DQR",
        receiver="ADS",
        content=(
            f"The API documentation needs improvement. "
            f"Current score: {api_score:.2f}, target: {quality_threshold}\n\n"
            f"Quality feedback:\n{quality_review.content[:300]}\n\n"
            "Focus on:\n"
            "- Adding more runnable code examples\n"
            "- Improving parameter descriptions\n"
            "- Adding cross-references to related modules\n"
            "Revise and resubmit."
        ),
        phase="critique",
    )
    improved = engine.step(improvement_message)
    improved_score = scorer.score_text(improved.content)
    print(f"Improved API doc score: {improved_score:.2f}")
else:
    print("Documentation quality meets threshold.")

Docs-as-Code Automation

Configure automated documentation validation:

automation_config = {
    "project": project_docs["name"],
    "pipeline": {
        "lint": "markdownlint docs/**/*.md",
        "link_check": "markdown-link-check docs/**/*.md",
        "build": "mkdocs build --strict",
        "spell_check": "cspell docs/**/*.md",
        "api_gen": "fcc generate-docs --output docs/api",
    },
    "ci_triggers": ["push to main", "pull request to docs/**"],
    "quality_gate": {
        "threshold": quality_threshold,
        "dimensions": list(doc_scores.keys()),
    },
}

import json
print("\nDocs-as-Code Automation Config:")
print(json.dumps(automation_config, indent=2))

Pipeline Summary

summary = {
    "project": project_docs["name"],
    "personas": ["IA", "CS", "DQR", "ADS"],
    "artifacts": {
        "architecture": len(doc_architecture.content),
        "content_strategy": len(content_strategy.content),
        "quality_review": len(quality_review.content),
        "api_documentation": len(api_docs.content),
    },
    "scores": doc_scores,
    "overall_score": overall,
    "gaps_addressed": len(project_docs["known_gaps"]),
}

print(json.dumps(summary, indent=2))

Exercises

1. Generate docs: Use the FCC DocGenerator (fcc.scaffold.doc_generator) to actually generate documentation files from persona specs.
2. RAG validation: Build a RAG pipeline over the documentation and verify that common questions are answered correctly.
3. Sitemap generation: Use the CLI fcc sitemap command to generate a documentation sitemap.
4. Cross-reference audit: Use the CrossReferenceMatrix to verify that all persona interactions are documented.

Summary

In this scenario you executed a docs-as-code pipeline:

• IA designed the documentation architecture with information hierarchy and navigation
• CS created a content strategy with priorities and style guide
• DQR reviewed quality across six dimensions with improvement recommendations
• ADS generated API documentation for undocumented modules
• A feedback loop improved documentation that fell below quality thresholds
• Automation configuration was produced for CI/CD integration

Next Steps

• Open Science Publication -- Publication workflow
• Persona Composition Patterns -- Reusable patterns