We Went All-In on Docs-as-Code. Here's What Actually Worked

General
1

Six months ago, I convinced our product teams to move our design system documentation from Confluence to a docs-as-code workflow. The pitch was compelling: version control, code review for docs, automated deployment, documentation that lives with the code it describes.

Now that we’re on the other side, I want to share what actually worked, what failed spectacularly, and the compromises we made.

The Setup

We moved from Confluence to Markdown files in Git, deployed via Docusaurus. Three product teams, mix of engineers, designers, and product folks all contributing to our shared design system.

What Worked Brilliantly

1. Engineers Actually Update Docs
When documentation is just another file in the repo, engineers update it. They’re already in the terminal, already making a commit. Adding a doc update to the same PR is trivial.

Before: “I’ll update the Confluence page later” (never happens)
Now: “Updated the component.md file in this PR” (actually happens)

2. Pull Request Reviews Caught Inconsistencies
Having docs in PRs means they get reviewed with the same rigor as code. We caught:

  • Incorrect prop descriptions before they shipped
  • Missing breaking change warnings
  • Examples that wouldn’t actually work with the new API

The review process for docs became just as thorough as code review.

3. Versioned Docs Matching Code Versions
This was huge for a design system. We can now say “these are the docs for v2.3” and “these are the docs for v3.0” and developers can see exactly what changed between versions.

For a component library supporting multiple product versions, this was transformative.

What Didn’t Work

1. Non-Technical Stakeholders Struggled
Product managers and designers who needed to contribute docs found Git/Markdown intimidating. We lost contributions from people who had valuable context but didn’t want to deal with branches and merge conflicts.

One PM told me: “I just want to add a note about when to use this component. I don’t want to learn Git workflows.”

2. Lost Rich Formatting
Confluence had embedded prototypes, videos, rich diagrams. Markdown is plain text. We lost the ability to embed interactive examples easily.

We worked around this with code sandboxes and external embeds, but it’s not as seamless as Confluence was.

3. Search Wasn’t as Good
Confluence’s full-text search was better than our static site generator’s search. We added Algolia DocSearch which helped, but it’s an extra dependency and configuration burden.

The Compromise We Reached

Not all documentation belongs in code. We now split our docs:

In Git/Markdown (docs-as-code):

  • Component API reference
  • Usage examples
  • Props and types
  • Technical implementation guides
  • Anything that changes with code

In Notion (traditional wiki):

  • Design principles and philosophy
  • Project planning and roadmaps
  • Meeting notes and decisions
  • User research findings
  • Cross-functional strategy docs

The Lesson

Docs-as-code is fantastic for technical reference documentation that needs to stay in sync with code. It’s less great for strategic documents, cross-functional collaboration, and content that needs rich media.

Match the tool to the documentation type. Not everything needs to be in Git.

My Advice if You’re Considering This

  1. Start small: Convert high-churn docs first (API references, frequently updated guides)
  2. Keep stable docs where they are: Don’t move everything just to move it
  3. Invest in tooling: Good static site generators, search, deployment pipelines matter
  4. Train your team: Git workflows aren’t obvious to non-engineers
  5. Accept you’ll have multiple systems: That’s okay, as long as you’re clear about what goes where

Who else has tried docs-as-code? What worked for you? What would you do differently?

2

This really resonates. We’re at TechFlow considering exactly this move, and your experience is super helpful.

The Question That’s Blocking Us

What static site generator did you settle on? We’re evaluating Docusaurus vs VitePress vs just building something custom with Next.js.

The requirements we’re trying to balance:

  • Fast build times (our docs are already 200+ pages)
  • Good search experience (Algolia integration or similar)
  • Versioning support (we ship new versions monthly)
  • Code playground integration (want live examples)
  • Dark mode (developers expect it)

Did you evaluate multiple options or go straight to Docusaurus?

The Visuals Problem

How are you handling diagrams and visual content in Markdown? This is one of our concerns.

We have a lot of architecture diagrams (currently in Lucidchart), API flow diagrams, sequence diagrams. Markdown doesn’t handle these natively.

Are you:

  • Using Mermaid.js for code-based diagrams?
  • Exporting images from design tools and committing them to Git?
  • Using external tools and linking?

My worry is that diagrams become stale if they’re not in version control with the code they describe.

The Cross-Functional Contribution Issue

Your point about non-engineers struggling with Git is exactly what I’m worried about. Our product team needs to contribute context about feature decisions, user research findings, etc.

Have you found any workflows that make this easier? Things we’re considering:

  • Web-based editors (NetlifyCMS, Forestry, etc.) that provide a UI for Markdown editing
  • Dedicated “doc writer” role who takes input from non-technical folks and does the Git work
  • Accepting that non-engineers will use a different tool and we’ll link between systems

What’s your take - is it worth trying to bridge the Git gap for non-engineers, or better to just accept you’ll have multiple documentation systems?

3

For mobile documentation, versioned docs are absolutely critical. Let me share how we’ve structured this at Uber.

The Multi-Platform Documentation Challenge

Mobile adds complexity because you’re not just versioning one thing:

  • iOS SDK versions
  • Android SDK versions
  • React Native wrapper versions
  • Flutter wrapper versions
  • API versions these SDKs talk to

Each combination can have different behavior, different APIs, different gotchas.

Our Structure: Monorepo with Platform-Specific Folders

We use a monorepo approach with clear separation:

docs/
├── ios/
│   ├── getting-started.md
│   ├── api-reference.md
│   └── migration-guides/
├── android/
│   ├── getting-started.md
│   ├── api-reference.md
│   └── migration-guides/
├── react-native/
└── shared/
    ├── concepts.md
    └── architecture.md

Common concepts live in shared/, platform-specific details live in platform folders. We use mdx to include shared content where needed.

The Tooling: Docusaurus with Versioning

We went with Docusaurus specifically for its versioning support. When we release iOS SDK v4.0, we run:

npm run docusaurus docs:version ios-4.0

This freezes the current docs as “ios-4.0” and creates a new “current” branch for ongoing development. Developers can switch between versions in the UI.

The win: We can link directly to docs that match the SDK version. When someone reports an issue, we can say “you’re on iOS SDK 3.2, here are the docs for that exact version” - no more confusion about whether docs match the code they’re using.

The Media Files Problem

Videos and screenshots bloat Git repos fast. Our solution:

  • Store media in CDN (S3 + CloudFront)
  • Reference by URL in Markdown: ![Screenshot](https://cdn.example.com/img.png)
  • CI pipeline uploads new media during deployment

Not perfect (media isn’t truly versioned with code), but manageable.

Platform-Specific Gotchas Documentation

We maintain a “Known Issues” section per platform version. This is where we document things like:

  • “iOS 14.2 has a networking bug that affects X”
  • “Samsung Galaxy S21 requires Y workaround”
  • “React Native 0.68 breaks Z integration”

These live in Git and get updated as we discover issues. Having them version-controlled means we can see historical issues and when they were resolved.

The Search Challenge

Alex mentioned search being a concern. We use Algolia DocSearch (free for open source, paid for private docs). The indexing happens automatically via their crawler.

Key configuration: we tag content with platform and version metadata so searches can be filtered. Searching for “authentication” can show iOS-specific, Android-specific, or shared results.

Question: How are others handling mobile-specific documentation? Separate repos per platform? Monorepo? Different tools entirely?

4

This is the exact tension we’re navigating - trying to serve engineering, product, design, and marketing, all of whom need to document different types of information.

The Current (Messy) State

Right now our documentation is scattered:

  • GitHub: Engineering architecture docs, API references
  • Notion: Product strategy, roadmaps, meeting notes
  • Confluence: Process documentation, team wikis
  • Figma: Design specs, component guidelines
  • Google Docs: Customer-facing guides, help articles

Every system made sense for its original purpose. But now we have no single source of truth. Cross-references break. Search is impossible across tools. People can’t find information.

The Hybrid Model We’re Proposing

What if we don’t try to force everything into one system, but instead create clear boundaries with explicit linking?

Technical docs in Git (docs-as-code):

  • API reference
  • SDK documentation
  • Architecture decision records
  • Technical runbooks
  • Code-adjacent documentation

Product/strategy docs in Notion:

  • Product strategy and vision
  • Feature prioritization and roadmaps
  • User research findings
  • Go-to-market plans
  • Cross-functional planning

Links between systems:

  • Technical docs include links to product context in Notion
  • Product docs link to technical implementation in Git
  • Clear ownership: engineering maintains Git docs, product maintains Notion docs

The Problem with This Approach

How do you keep cross-references valid?

Example: Product doc says “See technical architecture here: [link]”

  • What happens when that technical doc moves or is renamed?
  • How do we detect broken cross-tool links?
  • Who’s responsible for keeping external links current?

We don’t have a good answer yet. Some ideas:

  • Weekly automated link checker that crawls both systems
  • Clear URL stability promises (“these docs URLs won’t change”)
  • Accept some breakage and fix reactively

The Fear I Have

By optimizing docs-as-code for engineering, are we making it harder for product, design, and marketing to contribute their context?

Documentation quality comes from having the right people contribute the right information. If the tool creates barriers for non-engineers, we lose valuable perspective.

But if we keep everything in non-technical tools, engineers won’t maintain it and we get documentation drift.

How are others solving this? Is there a way to get the best of both worlds - technical precision and cross-functional accessibility?

5

We evaluated docs-as-code for our fintech platform and ran into compliance concerns that might be relevant for others in regulated industries.

The Enterprise/Compliance Challenge

In financial services, documentation isn’t just for developers - it’s for auditors, compliance officers, and regulators who need to review our systems.

The problem: Auditors don’t use Git. They don’t read Markdown. They want PDFs with version numbers, dated signatures, and audit trails that they can store as compliance artifacts.

Our Solution: Hybrid Pipeline

We went with docs-as-code for the engineering workflow, but added a compliance layer:

1. Docs-as-Code in Git

  • Engineers write Markdown
  • Standard Git workflow: branch, PR, review, merge
  • Deployed to internal docs site via CI/CD

2. Compliance Export Pipeline

  • CI automatically generates versioned PDFs on every release
  • PDFs include: version number, generation date, approver signatures
  • Archived in compliance system with full audit trail
  • Meets regulatory requirements for documentation retention

3. Best of Both Worlds

  • Engineers work in the tools they know (Git, Markdown)
  • Compliance team gets what they need (versioned PDFs, audit trail)
  • No manual conversion or duplicate maintenance

The Technical Implementation

Our CI pipeline runs:

  1. Markdown files → Pandoc → PDF generation
  2. Metadata injection (version, date, approver list)
  3. Upload to compliance document management system
  4. Notification to compliance team for review

We keep the Git workflow engineering-friendly while producing compliance-friendly artifacts automatically.

The Broader Lesson

Think about your full audience, not just developers.

Docs-as-code works great for engineering teams. But if you’re in:

  • Enterprise sales: Prospects might want PDF documentation to share internally
  • Regulated industries: Compliance may require specific formats and audit trails
  • Partner integrations: External partners might expect traditional documentation
  • Support teams: They might need printable troubleshooting guides

The solution isn’t to avoid docs-as-code - it’s to make sure your deployment pipeline produces the formats your various audiences need.

My Recommendation

Before going all-in on docs-as-code, ask:

  1. Who are all the consumers of your documentation?
  2. What formats and workflows do they expect?
  3. Can you automate format conversion to serve multiple audiences?

Docs-as-code can work in enterprise contexts, but you need to think beyond just the developer experience.

Anyone else dealing with documentation in regulated industries? How are you balancing developer workflows with compliance requirements?