Meet Diderot: The AI Assistant That Keeps Our Documentation in Perfect Sync

If you've ever looked at project documentation that's supposed to explain how something works, you know the sinking feeling:

Meanwhile, the actual setup process has evolved:

• config.json was replaced by environment variables six months ago
• The setup script now has three required flags that aren't mentioned
• The database migration guide moved to a different wiki page
• Two critical troubleshooting steps are missing entirely

Nobody updated the documentation. And nobody realized it was wrong until a new developer spent three hours hitting their head against the wall.

This is the reality of most software projects, and is often the first thing we run in to when coming into a new project. It's not that developers don't care about documentation. It's that when in the thick of building features, fixing bugs, and meeting deadlines, documentation updates always seem to be pushed to "next sprint."

The Problem: Documentation vs. Deliverables

Documentation drift is an industry-wide challenge. When you're brought in to solve urgent business problems such as scaling a failing system, fixing critical bugs, and delivering overdue features, documentation updates compete with immediate deliverables.

And when you're billing by the hour, it's a hard conversation: "We should spend time fixing gaps in the existing docs" versus "We should ship the feature your customers are waiting for."

Even with the best intentions, keeping documentation synchronized with a constantly evolving codebase requires constant vigilance:

• Code changes faster than docs: Three PRs merged today, each changing how something works
• Context evaporates quickly: Why did we change that API signature three weeks ago?
• Related updates get missed: Updating the API docs but forgetting to update the integration guide
• Examples go stale: Sample code that no longer compiles
• Screenshots become outdated: The UI changed but the documentation images didn't

The traditional solutions all have problems:

• Dedicated technical writers: Expensive and not always available
• Docs-as-code approaches: Still require developers to write the updates manually
• Auto-generated docs: Only cover API signatures, missing context and usage
• Quarterly documentation sprints: Always playing catch-up
• "Documentation is code comments": Helps developers, but not users or stakeholders

We needed a better approach that made the most of our modern tools and workflows.

Enter Diderot: The Documentation Assistant

Diderot is a specialized Claude Code sub-agent (named after Denis Diderot, the 18th-century philosopher who edited the Encyclopédie) that we created to solve a specific problem: helping developers keep documentation synchronized without the tedious manual work.

Let's be crystal clear about what Diderot does and doesn't do:

Diderot Does NOT:

• Replace technical writers
• Create documentation strategies
• Make decisions about what to document
• Handle user research or information architecture
• Write marketing content

Diderot DOES:

• Read code changes and understand what happened
• Update existing documentation with accurate information
• Generate comprehensive API documentation with examples
• Maintain cross-references between related sections
• Draft release notes based on recent changes
• Keep documentation formatting consistent

Think of Diderot as a documentation assistant, not a technical writer. He takes code changes and translates them into documentation updates.

How Diderot Works: Claude Code Sub-Agents

Diderot is what Claude Code calls a "sub-agent." Here's how it works:

1. Configuration File: Diderot lives in .claude/agents/diderot.md in your repository
2. Specialized Context: Diderot has project-specific knowledge about your architecture and documentation structure
3. Tool Access: Diderot can read code, search documentation, and update wiki pages
4. Invocation: You ask Claude Code to "use diderot to update documentation"
5. Execution: Diderot analyzes changes and systematically updates documentation

The magic isn't that Diderot "knows" your project. The magic is that Diderot knows how to analyze code changes and translate them into clear documentation based on the project context you provide.

Diderot's Adaptability: Same Agent, Different Projects

Just like our design agent Ray adapts to different visual contexts, Diderot adapts to different documentation needs. The agent configuration changes completely based on the project.

Example 1: Enterprise SaaS Platform

For a multi-tenant SaaS application with complex APIs:

Diderot configured for this project:

• Focuses on API completeness and accuracy
• Generates code samples in multiple languages
• Emphasizes error handling and edge cases
• Maintains strict versioning in documentation

Example 2: Internal DevOps Tools

For a suite of internal automation scripts and tools:

Diderot configured for this project:

• Prioritizes operational clarity over technical depth
• Creates runbook-style documentation
• Focuses on troubleshooting and common scenarios
• Uses informal, team-oriented language

Example 3: Open Source Library

For a JavaScript library published to npm:

Diderot configured for this project:

• Emphasizes ease of adoption
• Focuses on examples and quick wins
• Documents breaking changes clearly
• Maintains changelog rigorously

Same agent, different configuration, contextually appropriate documentation.

Real-World Example: Keeping Confluence Synchronized

Here's one way we use Diderot on client projects: automatically keeping Confluence documentation synchronized with code changes.

We're currently using this on a real estate management platform where code changes daily. Before Diderot, on a project like this, developers would spend 2-3 hours every couple weeks crawling through git logs trying to remember what changed. After Diderot, it takes 15 minutes each release cycle.

The full technical implementation, including GitHub Actions, change detection scripts, and the Atlassian MCP integration, is complex enough that we're saving it for a dedicated deep-dive post. But here's the basic flow:

1. Developers merge PRs with descriptive commit messages
2. A script analyzes what changed since the last documentation sync
3. Developer invokes Diderot: claude code "Use diderot to sync documentation"
4. Diderot reads the code changes, updates Confluence pages, maintains cross-references
5. Developer reviews and confirms the updates

The result: Documentation that's never more than a week out of date, with comprehensive API references that developers actually use while coding and user guides that are always up to date with the latest features.

Stay tuned for a deep-dive post where we'll share the complete automation setup, including the change detection logic, GitHub Actions workflow, and how to configure the Atlassian MCP server.

When You DO Need a Technical Writer

Diderot is not a technical writer replacement. Here's when you absolutely need professional technical writing expertise:

• Documentation strategy: What to document and for whom
• Information architecture: Organizing content for discoverability
• User research: Understanding what users actually need
• Tutorial creation: Teaching users how to accomplish complex goals
• Style guide development: Establishing voice, tone, and standards
• Accessibility compliance: Ensuring documentation meets WCAG standards

Diderot helps developers between technical writer engagements. He helps us:

• Keep existing documentation synchronized with code
• Generate reference documentation that technical writers can polish - Instead of starting from scratch, technical writers receive comprehensive docs, complete with examples and context, ready to refine for style and clarity
• Maintain consistency during active development
• Draft release notes that product managers can refine - Product managers get detailed, accurate summaries of what changed, which they can transform into customer-facing announcements without hunting through git logs
• Provide accurate information for support teams

But he doesn't replace the strategic thinking and user-centered design that professional technical writers bring.

Configuration Example: Setting Up Diderot

Want to use Diderot on your own project? Here's the structure:

1. Create the Agent Configuration

Store in .claude/agents/diderot.md:

2. Add Project-Specific Knowledge

Include information that helps Diderot understand your context:

• Architecture diagrams or descriptions
• Common terminology and acronyms
• Relationships between documentation sections
• Examples of well-documented features
• Links to style guides or templates

3. Establish a Workflow

Create a repeatable process:

4. Iterate and Refine

As you use Diderot:

• Save successful documentation patterns
• Add examples to the configuration
• Refine the rules based on what works
• Document edge cases you encounter

Download Diderot's Configuration

Want to see a complete configuration? We're sharing a template you can adapt:

Download the Diderot configuration template →

The template includes:

• Full agent configuration structure
• Examples for different project types (Enterprise SaaS, DevOps Tools, Open Source)
• Common documentation standards and formatting preferences
• Troubleshooting rules and edge cases
• Workflow examples for common scenarios

You can adapt this to your project by updating the project context, documentation platform details, and specific standards.

The Bottom Line

Diderot doesn't replace technical writers. He helps developers keep documentation synchronized without spending hours on manual updates.

By analyzing code changes and systematically updating documentation, Diderot:

• Saves hours of manual git log archaeology
• Maintains accuracy as code evolves
• Provides comprehensive reference documentation
• Keeps cross-references up to date
• Drafts release notes automatically

For our client projects, Diderot has transformed documentation from a quarterly burden into a weekly routine. Developers can focus on writing great code, and documentation stays current.

And when we eventually bring in a technical writer to create tutorials and user guides, they have accurate, comprehensive reference documentation to build from.

That's the power of specialized AI assistance: not replacing human expertise, but making human expertise more effective.

Struggling to keep your documentation synchronized? Our team specializes in creating maintainable systems that scale with your business. Let's talk →