The team works in different languages, deals with different tools to extract code comments, and ends up with Doxygen output that looks vintage. The default HTML lives as a separate site with its own search, its own navigation, no easy way to make it match the rest of the docs. So even when they publish it, nobody reads it.

Here’s how we work around it.

The problem isn’t Doxygen

Doxygen is great at the part most people don’t want to do themselves: parsing code comments and extracting structured information. Class hierarchies, function signatures, parameter descriptions, return types, defaults. It works across C++, Java, and a long list of other languages.

The problem is what comes out of the box. The HTML looks like it was built two decades ago. It can’t be styled to match your navigation. It uses its own search bar, separate from the main one users already know. It feels like a different product altogether.

So engineers close the tab. Writers stop pushing for it. The reference docs either don’t get published, or they get published and nobody reads them. Neither is good.

Use Doxygen as a parser, not a publisher

Doxygen also generates XML alongside HTML. Same structured data, just in a format you can do something with.

From that XML you can produce markdown, RST, or whatever format your docs platform expects. The API reference becomes part of your docs instead of a separate site bolted on. Sphinx, Docusaurus, Antora, MkDocs, whatever you’re already using.

The big shift is control. You decide how the reference looks. You can hide internal helpers Doxygen would otherwise expose, like for example group classes by feature instead of file. Strip out the noise (private members, autogenerated boilerplate, deprecated APIs nobody uses) and only show what your users actually need. None of that is possible with the default HTML.

We did this for ScyllaDB’s Driver docs. Built a custom extension that consumed the Doxygen XML and rendered it as native Sphinx pages.

The API reference now looks like every other page on the site. Same theme, same navigation, same search. When the team adds new libraries, the reference updates from the comments in the code, automatically.

The downside is that you have to write the extension if one doesn’t exist for your platform. But that’s a one-time effort, and the alternative is maintaining reference docs by hand and watching them go stale every release.

Why this matters more now

Structured API reference is also exactly what AI agents need to write correct code. When an agent has to know what parameters a function takes, or what its return type is, the reference is more reliable than any tutorial. It comes straight from the source.

Doxygen’s XML already contains all of that. Publishing it properly means it’s useful for both humans and AI, not just one or the other.

So is Doxygen going out of style?

The template is. The tool isn’t. Doxygen still does the hardest part: extracting structured documentation from code.

Throw away the HTML. Keep the XML.

We started following it. Within a few minutes, we had our answer. Some steps worked fine. Others didn’t compile. One snippet referenced a method that no longer existed. Another used a dependency version from two releases ago.

The client didn’t know. The page looked great. Clean formatting, syntax highlighting, clear explanations between each code block. Nothing about it screamed “broken.” You had to actually run the code to find out.

This is what happens when code lives in Markdown files, disconnected from any build process. Nobody re-runs examples after every release. The docs look fine. They just don’t work anymore.

Keep examples in a project, not in your docs

The fix: stop pasting code into Markdown files. Instead, keep your examples in a separate project that actually compiles.

The project lives in its own folder near the docs, with real dependencies, a real build step, and version control. Your docs import snippets from this project instead of containing them directly. When the product releases a new version, you update the project. If a snippet breaks, the build fails. You find out before your users do.

You can also version your examples properly. Need docs for v2 and v3? The project has branches for each. You bump the dependency, run the build, and know immediately what still works.

Once we set this up for the client, updating code examples stopped being scary. It went from editing a Markdown file and hoping it still worked to making a code change with a build. New users following the getting started guide actually got to the end.

It does mean maintaining a project alongside your docs. But the alternative is finding out your examples are broken when a user does.

If you want the practical details on how to set this up, I wrote a step-by-step guide a few years ago.

The client said it casually, like it was just how things worked. The system rebuilt the entire site every time. Even for a one-word fix.

This is more common than you’d think. And it kills documentation quality in ways that aren’t obvious.

Slow builds make docs worse

When a build takes 30+ minutes, nobody verifies small changes. You fix a typo, push it, and hope for the best. You don’t wait half an hour to check if the formatting looks right.

Writers stop iterating. They batch changes into big updates instead of making frequent small improvements. Reviews slow down because nobody wants to trigger another long cycle just to see a preview.

The result: fewer updates, more errors that slip through, and a team that treats docs as something to avoid touching.

Why this build was slow

The project used Sphinx. The build produced both HTML and PDF outputs. Every build generated everything from scratch: the full HTML site and the complete PDF manual.

In this case, the PDF was the bottleneck. Sphinx uses LaTeX to produce PDFs, and LaTeX is slow. One monolithic PDF meant one monolithic build. Change a paragraph in the authentication guide and the system rebuilds a 1400-page PDF from scratch.

On top of that, the HTML and PDF builds ran sequentially. One waited for the other. So even if the HTML build was fast, the PDF blocked the whole pipeline.

What we changed

Two things:

We split the PDF into chapters: Instead of generating one massive PDF, we configured Sphinx to produce separate PDFs per section. Authentication docs, API reference, deployment guide, each their own PDF.

Change the auth docs? Rebuild only that PDF. The rest stay untouched.

We separated the HTML and PDF builds: They now run in parallel instead of sequentially. Writers can preview their HTML changes immediately while the PDFs generate in the background.

The result

Build time dropped from 30 minutes to under 5 for most changes.

But the real impact isn’t the number. It’s what changed in the team’s behavior. Writers started verifying their changes again. Small fixes got pushed the same day instead of being batched for “next sprint.” Reviews got faster because previews were available in minutes.

The docs got better because the build time got out of the way.

Slow builds are a silent documentation killer. Nobody complains about them in sprint retros. But they quietly push teams away from touching the docs.

If your build takes more than 10 minutes, it’s worth investigating why.

The review process was simple: build the docs locally, check for broken links, formatting issues, rendering problems. Then approve.

Except reviewers weren’t building the docs locally. They were skimming the markdown in the PR and hitting approve. “LGTM!” Without ever seeing the actual rendered output.

Can’t blame them. Building docs locally means cloning the repo, installing dependencies, running a build command, waiting, then navigating to localhost. That’s five minutes of friction for a review that “should” take two. So they skip it and pray it’ll render well.

This isn’t a discipline problem

It’s a friction problem.

We don’t skip important steps because we’re lazy. We skip them because the effort feels disproportionate to the task. A quick review shouldn’t require a local dev environment. But it did. So the “quick review” became “skim the markdown and approve.”

The fix was simple

We added automated PR previews. Every pull request now generates a deployed preview and drops the link in the PR comments.

“Click this link” replaced “build it locally.” One click versus five minutes of setup. Guess which one people actually do.

Review quality went up immediately. Not because we trained anyone, not because we wrote stricter guidelines, not because we added more process. We just removed the friction.

The pattern

This isn’t unique to doc reviews.

Style guides nobody follows because checking them is a chore → put linting in CI and suddenly everyone complies.

Broken link checks that never happen because clicking every link is tedious → automate it and they get caught before merge.

The step is important. We all agree it's important. We still skip it. Every time, the reason is the same: too much friction for the value it delivers in the moment.

Instead of asking “why aren’t people following the process?”, ask “what’s making this process hard to follow?”

If you've run into something similar (a process that kept getting skipped until you found a way to reduce the friction) I'd love to hear about it in the comments.

That’s a fine goal. But it misses the bigger opportunity.

The real value isn’t answers. It’s visibility.

Every question a user asks reveals something:

• A confusing explanation

• A missing example

• A gap in the product itself

When teams add an AI assistant to their docs, they don’t just get faster support. They get a window into exactly where users are struggling.

When your AI can’t answer, that’s not a failure. It’s a signal.

That shift changes everything.

From static reference to feedback loop

Traditional documentation is a one-way broadcast. You write it, publish it, and hope it helps.

But when you track what users actually ask, documentation becomes a conversation. You see patterns. You spot the same confusion appearing again and again. You find the blind spots your team never noticed because you’re too close to the product.

Suddenly, your docs aren’t just supporting users. They’re teaching you what to fix.

The insight you’re leaving on the table

If your documentation only answers questions, you’re capturing maybe 10% of its potential value.

The other 90%? It’s in the questions themselves.

• Which features confuse people most?

• Where do users get stuck in onboarding?

• What terminology doesn’t land?

With an AI assistant, that data exists. Most teams just aren’t collecting it.

A good AI assistant surfaces which questions your docs can’t answer, ranked by frequency.

From insight to action

Knowing where the gaps are is only half the problem. Fixing them is where most teams stall.

The best tools help you close those gaps with clear guidance on where to start.

Start here

Next time you look at your docs, don’t ask “did we cover everything?”

Ask “what are users still asking, and why?”

The answer will show you exactly what needs to change.

“Hey, can you review this?”

Two days later, I had 10 comments. Four of them were about commas. Two more about whether colons introducing lists should be bold or not. Another spent three paragraphs debating whether “setup” should be one word or two.

Not a single comment mentioned that step 4 was completely broken. The command I told users to run didn’t actually work.

Why vague requests produce surface feedback

When you ask “can you review this?” without direction, people default to whatever stands out first.

Typos. Formatting. Word choice. Easy to spot, easy to comment on.

“Review this” could mean:

• Check if the logic makes sense

• Verify the code runs

• Look for security issues

• Test the user flow

• Proofread for typos

• Check if the tone is right

Without knowing what you need, people pick the easiest path.

The cost of unfocused reviews

You spend hours sorting through comments that don’t help. Reviewers spend energy on things you’re going to ignore or fix a later phase. The real issues never get caught.

I’ve seen teams spend three review cycles debating admonition colors while nobody notices the registration flow is broken. Product and docs ships. Users can’t sign up. “But we had five people review it.”

Yeah, they reviewed the wrong things.

How to ask for useful feedback

Tell exactly what to look at:

• “Does the getting started flow make sense?”

• “Are the code examples working on your end?”

• “Is the reference documentation for this function complete?”

And tell them what to ignore:

• “Don’t test authentication, QA is handling that”

• “Ignore formatting, I’ll run the linter”

• “Skip the intro section, it’s placeholder text”

• “Don’t worry about performance yet, that’s next sprint”

If you’re the one being asked to review

This works the other way too. Someone sends you “can you review this?” with no context.

Ask “What kind of feedback are you looking for?”

Takes 30 seconds. Saves both of you from a useless review cycle.

See something else? Mention it. But stay focused.

If you spot a bug or broken link while reviewing, point it out. If something’s unclear, say so. Of course, leave things better than you found them. This isn’t about ignoring obvious problems.

But keep the ultimate goal in mind. If someone asked you to review the tutorial flow and you spend 15 minutes looking for oxford commas, you’ve lost the plot. Don’t forget what they actually needed.

Just don’t forget what they actually needed.

How to make this normal

Next time you ask for a review, add one specific question. When someone asks you to review something, ask what they’re looking for.

You can create simple templates:

Review Request:

• What changed: brief summary

• What to focus on: specific concerns

• What to skip: things handled elsewhere

• Questions: what you’re unsure about

What this comes down to

Everybody wants to help. But without direction, it’s easy to loose focus on whatever jumps out first. And that’s almost never what you need.

If you want useful feedback, ask useful questions.

Be specific. Point toward what matters. Call out what to ignore.

You’ll get faster reviews, better feedback, and fewer arguments about commas.

We suggested adding a feedback widget. A small button: “Was this helpful?”

One week later, 12 users had left feedback. Not one was positive.

“Step 3 is missing.” “This example doesn’t work.” “I’ve read this four times and I’m still confused.” “Where’s the actual code?”

Those 5 minutes weren’t engagement. They were users scrolling up and down, re-reading, trying to figure out what was missing.

Good metrics, bad experience

The analytics showed what users did. The feedback showed why.

The team fixed everything in 48 hours. Added the missing step. Replaced the broken example. Clarified the confusing parts. Added code snippets where users expected them.

Session time dropped to 3 minutes. But now users were finishing successfully instead of giving up confused.

You need both

Quantitative data shows behavior. Qualitative data explains it.

Your analytics will tell you users spent 5 minutes on a page. Your users will tell you they spent 5 minutes confused.

One number can mean two completely different things.

Formatting notes sit beside broken code examples. The team spends 30 minutes debating comma placement while critical bugs slip through.

To fix this, I introduced a tagging system for review comments.

The problem: No shared language for priority

Reviewers leave comments without indicating priority. Contributors treat every comment as blocking.

The breakdown happens in three ways:

• Contributors waste time on non-issues: Someone suggests “maybe use a bullet list here instead of numbered?” The contributor spends an hour reformatting. Turns out it was just a passing thought.

• Critical issues get missed: Seventeen comments deep, one mentions the API endpoint is wrong. The PR merges. Users hit a broken example. Support tickets pile up.

• Review cycles multiply: Contributor fixes what they think matters. Reviewer expected different fixes. Another round. The two-day PR becomes a two-week ordeal.

The root cause: no shared language for priority. And even when something clearly needs fixing, the comment doesn’t say what kind of fix. Is it a code bug? A clarity problem? A style preference? Contributors guess, guess wrong, and the cycle repeats.

The fix: severity + category

A two-part tag for every review comment.

Severity tells contributors the importance of the fix:

• blocker: Must fix before merge. Breaks functionality or blocks critical understanding.

• improvement: Should fix before publication. Improves clarity, structure, or usability.

• optional: Personal preferences, stylistic suggestions, future ideas.

Category

Category tells contributors what kind of fix at first glance:

• clarity: Confusing or incomplete explanations.

• bug Incorrect code, wrong output, factual errors.

• organization: Issues with flow, structure, content order.

• style: Wording, formatting, tone.

• consistency: Conflicts with other sections, terminology, or examples.

Add others if your team needs them. Keep the list short.

Some examples

(improvement, clarity): Step 3 assumes readers know what environment variables are. Add a one-line explanation or link to prerequisites.

(blocker, bug): This code example throws an error. Missing import statement at the top.

(improvement, organization): Move the troubleshooting section before advanced configuration. Users hit errors at the basic level first.

(optional, clarity): This explanation works, but the second paragraph repeats the first. Consider cutting it.

What changes after tagging

• Contributors know what to fix immediately. Scan for blocker tags. Fix those first. Everything else waits.

• Contributors feel less overwhelmed: Seventeen comments looks terrifying. Two blockers, eight improvements, seven optional? Manageable.

• Debates end faster: No more “should we merge this or wait?” If there are no blockers, merge. Track improvements for follow-up.

• Review culture improves: New reviewers see the pattern. They start tagging their comments. The team develops shared expectations.

What this doesn’t fix

• Tagging doesn’t fix slow reviewers. If your team takes three days to look at PRs, tags won’t help. That’s a process problem.

• Tagging doesn’t fix bad feedback. “(blocker, style): I don’t like this wording” is still bad feedback. Add context. Explain why.

• Tagging doesn’t replace good judgment. A reviewer still needs to know what’s actually a blocker vs. a preference.

How to start

Don’t overthink it. Start tagging your review comments this week.

Put the tag at the start of each comment. Make it visible.

Within two weeks, you’ll see fewer debates about what blocks merge. Contributors will know what to fix first. Reviews will move faster. Others will copy you.

The system works because it forces one decision upfront: is this blocking or not?

Make that decision explicit. Stop wasting time guessing.

Then things drift apart.

The problem

Engineer adds a new configuration property:

export interface DatabaseConfig {
  isolationLevel?: IsolationLevel;
  enableSsl?: boolean; 
  retryAttempts?: number; // New property
}

Deploys it. Forgets to update the docs.

Three weeks later, a user reads the documentation. No mention of retry_attempts. They assume the feature doesn’t exist. Or worse, they assume the default behavior and it breaks their setup.

Support ticket arrives.

This pattern repeats with every config change. Properties added, docs lag behind. Properties deprecated, docs still show them. Default values change, docs show old defaults. The same thing happens with API parameters, CLI flags, environment variables, error codes. Anywhere docs describe what exists in code.

The root cause is simple: code and docs live in two places with different owners. Code changes frequently, gets reviewed and tested, and is always correct. Docs update manually, have no automated checks, and drift out of sync. Two systems that don’t talk to each other.

The solution: define once, generate the rest

There are two approaches.

Approach 1: Define a schema

Write a machine-readable schema as your source of truth. From it, generate code, docs, and everything else.

properties:

  - name: isolation_level
    required: true
    type: string
    enum: [READ_UNCOMMITTED, READ_COMMITTED, REPEATABLE_READ, SERIALIZABLE]
    example: READ_UNCOMMITTED
    description: Transaction isolation level

  - name: enable_ssl
    required: false
    type: boolean
    default: true
    description: Enable SSL encryption for database connections

  - name: retry_attempts
    required: false
    type: integer
    default: 3
    description: Number of times to retry failed connections

From this schema, generate server code, client SDKs, API documentation, examples, interactive API explorers. The schema is your contract. Everything else derives from it.

An additional benefit: by decoupling the schema from actual code, you facilitate conversations about the contract. Teams can review and agree on the API structure before implementation.

This approach works best when open standards exist for your technology: OpenAPI for REST APIs, GraphQL schemas, Protocol Buffers for gRPC, JSON Schema, AsyncAPI for event-driven architectures.

If no standard exists, you need to build the generators yourself, which could be a stopper if resources are limited.

Approach 2: Annotate your code

Add documentation as annotations directly in your code. Generate docs from it.

Example: TypeScript with JSDoc

export interface DatabaseConfig {

  /** Transaction isolation level
   * @required
   * @example ‘READ_COMMITTED’
   */
  isolationLevel?: IsolationLevel;

  /** Enable SSL encryption for database connections
   * @default true
   */
  enableSsl?: boolean;

  /** Number of times to retry failed connections
   * @default 3
   */
  retryAttempts: number;
}

From annotated code, generate the intermediate schema and the reference documentation.

Check if your programming language already has a standard: JavaDoc for Java, Google-style docstrings for Python, JSDoc for TypeScript/JavaScript. If no convention exists, define one. Document it. Stay consistent.

This approach is simpler than defining schemas, especially when you don’t have code generators available.

How to implement it

Document your source of truth. Write your schema file or add annotations to your code. Include descriptions, types, defaults, constraints.

Be thorough. This is the single source. Everything generates from it.

Choose your generator. Check if existing plugins work for your docs platform. Rendering OpenAPI in Docusaurus? There’s a plugin. Sphinx? Extension available.

But if you need something specific (TypeScript docs in Antora, for example), you’ll need a custom solution.

Key tip for annotations: Always generate an intermediate schema file (JSON or YAML) first. Don’t try parse code annotations directly in your docs build.

If you need a custom extension, that requires dev work. We can help with that.

Add to CI. On every commit: validate the source, regenerate documentation, fail the build if validation fails. On merge: deploy updated documentation automatically.

Start small

You don’t need to generate everything on day one.

Start with one configuration file. Generate just the reference table. Keep the rest manual. You can still have custom, hand-written guides alongside generated reference sections. Prove it works. Then expand.

A common objection

“But our configuration is complex. We need custom documentation.”

You can still have it. Generate the reference section (the part that can be autogenerated and reused in guides). Keep step-by-step guides manual.

The result

Engineer adds a new parameter. Commits the code. The docs update automatically.

Three weeks later, a user reads the documentation. The parameter is there.

No support ticket this time.

The content was technically correct but generic. Corporate tone that didn’t match our style. Examples that could have been for any product. Missing the context that makes ours different.

The AI wasn’t the problem. I was asking it to write documentation without giving it the information it needed.

What changed

We now keep a context file next to the codebase. Every time I prompt an AI agent, I feed this file in first.

Without context file:

“Welcome to Biel.ai! We’re excited to help you get started with our amazing AI chatbot platform.”

With context file:

“Biel.ai trains on your documentation to answer technical questions. This guide gets you from zero to a working chatbot in 10 minutes.”

The second version matches our voice. Uses our positioning. Focuses on the user.

Think of it like onboarding a new team member. You don’t say “go write docs” and expect great results. You explain the product, the users, the style, the constraints. Same with AI.

How to build one

Create a markdown file next to your codebase. Include:

1. Three sentences about your product

2. Who uses it and why (specific personas, not “developers”)

3. How you write, what to avoid, examples of good vs. bad. Paste 3-5 examples from your best docs (this is your voice)

4. Common use cases (actual workflows)

5. Technical details (stack, repo structure, naming conventions)

Commit it so it versions with your code. Update it as you find the AI producing results that miss the mark.

Use it for docs, marketing copy, support responses, tutorial content, release notes. Anywhere AI writes for your product.

More advanced: If your IDE supports rules (like Cursor’s .cursor/rules), add the context file there. It’ll feed into every prompt automatically.

An unexpected benefit

The context file started aligning the whole team. New engineers read it to understand positioning. Writers use it for consistency. Product managers reference it when describing features.

It became our single source of truth for “how we talk about this product.”

Worth the 30 minutes to set up.

Here’s a typical configuration table:

Clean at first glance. Painful in practice.

The problems

• Limited space for descriptions: That sslmode property has four possible values with different behaviors. The table cell gives you 50 characters. You either truncate important information or your table explodes horizontally.

• Horizontal scrolling: Wide tables scroll off the screen. Users on mobile give up. Users on desktop get annoyed.

• Hard to edit: Try adding a line break or list inside a Markdown table cell. You’ll remember why you hate tables.

• Unnecessary fields: Not every property is required. Not every property has a default. But tables force you to create columns for everything, leaving empty cells everywhere.

• Inflexible: Need to add “Available values” as a column? Rebuild the entire table.

An alternative approach: description lists

postgresql.connection.hostname

The hostname of the PostgreSQL server.

Required

Type: String

Example: localhost

postgresql.connection.port

The port on which PostgreSQL is running.

Type: Integer

Default: 5432

postgresql.connection.sslmode

Determines whether to use SSL and the level of verification required.

Type: String

Default: prefer

Available values:

- disable: SSL is not used for the connection.

- allow: First attempts a non-SSL connection. If that fails, attempts an SSL connection.

- prefer: First attempts an SSL connection. If that fails, attempts a non-SSL connection.

- require: SSL is used for the connection.

Why it works

• Space for actual explanations: Complex properties get the room they need. sslmode gets four detailed options instead of a cramped sentence.

• No horizontal scrolling: Content flows vertically. Works on any screen size.

• Easy to edit: Update one property without touching the others. Add lists, code blocks, whatever you need.

• Automatic linking: Most documentation systems generate anchor links for each property. Users can share #postgresql.connection.sslmode directly.

• Only show relevant fields: Required properties show “Required.” Optional properties don’t. No empty cells cluttering the page.

The catch

Most documentation systems don’t support complex description lists by default. You’ll likely need to write a custom extension or use a plugin.

Worth it for complex configurations. Not worth it for simple two-column data.

Real-world examples

• MongoDB Configuration Parameters

• Sphinx Configuration

• Stripe API Pagination

Conclusion

Tables aren’t evil. They’re just overused for the wrong problems.

Use tables for:

• Simple data (2-3 columns)

• Short descriptions

• Uniform properties (all have same fields)

Use description lists for:

• Complex properties with multiple options

• Long explanations

• Properties with different fields (some required, some with defaults, some with neither)

Now, you have another tool in your chest to enhance your documentation. Use it wisely.

Someone captures a screenshot, edits it with the OS image editor, adds it to the docs. Three months later the UI changes. Nobody can find the original. Nobody knows how it was edited. Someone creates a new screenshot that looks completely different from the rest.

Designers don’t work this way. Neither should you.

Use a design tool

Stop editing screenshots in your OS image editor.

Stop editing screenshots in your OS image editor. Use Figma or Draw.io instead. Create one canvas per documentation page. All your screenshots live in one place, with consistent sizes and styles.

When you need to export, choose your format and resolution. When the UI changes, you know exactly where to find the source file and what to update.

Build a reusable library

Create components you use across all screenshots:

• Highlight boxes (consistent color and style)

• Arrows pointing to UI elements

• Step numbers for tutorials

• Blur overlays for sensitive data

When a screenshot becomes outdated, replace the base image and reuse your existing highlights and arrows. No recreating everything from scratch.

Store editable versions with your docs

Put the editable files (.fig, .drawio) in your documentation repository.

When someone needs to update a screenshot six months from now, they can. They’re not starting from scratch or guessing how you created the original.

This doesn’t prevent screenshots from going stale

Nothing does. But it makes updates faster. Your future self (or your teammate) opens the design file, swaps the screenshot, and exports.

The consistency is a bonus. When all your screenshots use the same highlight color and arrow style, your documentation looks professional instead of cobbled together.

Treat screenshots like design assets, not disposable images.

Here’s how to make code examples easier to maintain and test.

Note: I’m using Sphinx here, but the principles apply to any documentation system.

The problem with inline code

Here’s a typical documentation page mixing code and text:

Example
=======

To order a pizza using the Python SDK, call the
``order`` method by passing the
pizzas you want, your customer ID, and the delivery
service as the parameters.

The following examples show you how to order a 
Hawaiian pizza to take away.

.. code-block:: python

    api = pizza.Api()

    api.order(
      pizzas=[
      {’code’:pizza.pizza_codes.HAWAIIAN, 
        ‘quantity’:1}
        ], 
        customer_id=’dgarcia360’, 
        serviceType=pizza.service_types.TAKE_AWAY)

When the SDK updates, you have to:

1. Find every affected example.

2. Copy/paste each one into a file.

3. Test it manually.

4. Update the docs.

You can’t verify the code you tested is the same code displayed in the docs.

Step 1: Separate code from text

Move code examples to separate files:

documentation-project/
├── index.rst
├── order.rst
├── examples/
│   ├── javascript
│   └── python
│       ├── order.py
│       ├── tests/
│       └── requirements.txt

Now you can:

• Run the code and add tests

• Use linters to check formatting

• Execute examples without copy/paste

Step 2: Import code into docs

Use a directive like Sphinx’s literalinclude directive to render code files:

.. literalinclude:: examples/python/order.py
    :language: python

Step 3: Highlight code subsets

Sometimes you only need part of a file. Use comment tags to mark sections:

# block 01
api = pizza.Api()
# endblock 01

# block 02
api.order(
    pizzas=[
        {’code’:pizza.pizza_codes.HAWAIIAN, 
        ‘quantity’:1}
    ], 
    customer_id=’dgarcia360’, 
    serviceType=pizza.service_types.TAKE_AWAY)
# endblock 02

... and then, detect those tags with the help of the directive.

.. literalinclude:: /pizza/order.py
    :language: python
    :start-after: # block 02
    :end-before: # endblock 02

You can also use line numbers:

.. literalinclude:: /pizza/order.py
    :language: python
    :lines: 10-15

But line numbers break easily. Add one import statement at the top of the file and every line number shifts. Your docs now show the wrong code. Comment tags stay anchored to the code they mark, even when the file changes.

The new update process

When the SDK releases a new version:

1. Update dependencies in the examples folder.

2. Run the code and see what fails.

3. Fix the broken examples.

4. Push changes. Docs update automatically.

The real benefit

This doesn’t eliminate code example maintenance. It just makes it testable.

When your tests pass, your code examples work. When they fail, you know which examples broke and can fix them before users find out.

Separate code from docs, test it, and import it. That’s it.