Then we cross-referenced their analytics. A handful of old URLs were responsible for most of the search traffic to the site. Pages that had ranked well for years, that partners linked to, that customers had bookmarked. None of those URLs would exist on the new site.

If we’d launched without a redirect plan, they would have lost months of search traffic overnight. Customer bookmarks would break. Partner integrations would point to dead pages.

Most of the energy in a migration goes into the new platform. What it looks like, how it’s organized, what tech stack to use, where to host it… The old URLs barely come up.

But you’re not just moving content. You’re moving content that other people have linked to, in places you don’t control. Search engines, partner sites, support emails, bookmarks, internal wikis. You can’t update any of those. The only thing you can do is make sure the URLs they point to still resolve.

So if you’re planning a docs migration, ask one question: what happens to every existing URL?

Whether you’re reviewing a plan from a vendor or running the project internally, this is the check that matters. If nobody on the team can answer it, redirects aren’t going to happen. They’ll get pushed to “after launch” and never come back.

The new site can be perfect. But every old URL that breaks costs you traffic, support tickets, and a bit of trust.

It’s a fair question. Doxygen’s default output looks vintage, and most people who land on it don’t stick around.

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.

The problem is what comes out of the box. The HTML looks like it was built two decades ago, and it lives as a separate site with its own search, disconnected from the docs 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, in a format you can actually work 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.

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, but the tool isn’t. Doxygen still does the hardest part: extracting structured documentation from code.

We started following it. Within a few minutes, we had our answer. Some steps worked fine, but others didn’t even 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. The docs look fine, but 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’re not going to wait half an hour to check whether the formatting looks right.

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

The result: fewer updates go out, more errors slip through, and the team starts treating the docs as something to avoid touching.

Why this build was slow

The project used Sphinx, and every build generated everything from scratch: the full HTML site and a complete PDF manual.

The PDF was the bottleneck. Sphinx uses LaTeX to produce PDFs, and LaTeX is slow. One monolithic PDF meant one monolithic build, so changing a single paragraph in the authentication guide rebuilt a 1,400-page PDF from scratch.

It got worse: the HTML and PDF builds ran one after the other. Even when the HTML build was fast, it sat waiting for the PDF to finish before the pipeline completed.

What we changed

We split the monolithic PDF into separate files, one per section. Authentication, API reference, deployment guide, each with its own PDF. Now changing the auth docs rebuilds only that PDF and leaves the rest untouched.

Then we stopped running the two builds in sequence. HTML and PDF now build in parallel, so writers can preview their HTML changes right away while the PDFs generate in the background.

The result

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

But the number isn’t the point. What mattered was how the team’s behavior changed. Writers started checking their work again. Small fixes went out the same day instead of waiting for “next sprint.” Reviews sped up because previews were ready in minutes. The docs got better because the build time got out of the way.

Nobody complains about slow builds in sprint retros. They're a silent documentation killer, quietly pushing teams away from touching the docs.

If yours takes more than 10 minutes, it's worth finding out why.

The review process was supposed to be 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 rendered output.

You can’t really 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 hope it renders fine.

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 this one did. So the “quick review” quietly 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 get ignored when checking them by hand is a chore, so you put the linter in CI and suddenly everyone complies. Broken link checks never happen because clicking every link is tedious, so you automate them and they get caught before merge.

The step is important. Everyone agrees it’s important. We still skip it, and every time the reason is the same: too much friction for the value it delivers in the moment.

So 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 were about commas. Two more debated whether colons introducing lists should be bold. Another spent three paragraphs on 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?” with no direction, reviewers 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 their energy on things you’ll ignore or fix in a later phase. And the real issues never get caught.

I’ve watched teams spend three review cycles debating admonition colors while nobody noticed the registration flow was broken. Product and docs ship, users can’t sign up, and someone says “but we had five people review it.” They did. 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”

The second half matters as much as the first. Telling people what to skip is what frees them to focus on what you actually need.

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 they’re looking for. It takes 30 seconds and saves you both from a useless cycle.

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

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

That doesn’t mean ignoring obvious problems. If you spot a bug or a broken link while reviewing, point it out. If something’s unclear, say so. Leave things better than you found them. But keep the goal in mind: if someone asked you to review the tutorial flow and you spend 15 minutes hunting for Oxford commas, you’ve lost the plot.

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.

A simple template helps:

• What changed: brief summary

• What to focus on: specific concerns

• What to skip: things handled elsewhere

• Questions: what you’re unsure about

What it comes down to

Everybody wants to help. But without direction, it’s easy to lose 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, and call out what to ignore. You’ll get faster reviews, better feedback, and fewer arguments.

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, and added code where users expected it.

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 those 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, and 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 is the missing shared language for priority. And even when something clearly needs fixing, the comment doesn’t say what kind of fix it is. 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 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, but 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, because that’s a process problem.

It doesn’t fix bad feedback either. “(blocker, style): I don’t like this wording” is still bad feedback. The reviewer still has to add context and explain why.

And it doesn’t replace good judgment. A reviewer still needs to know what’s actually a blocker versus a preference.

How to start

Don’t overthink it. Start tagging your review comments this week, with the tag at the start of each comment where it’s visible.

Within two weeks you’ll see fewer debates about what blocks merge. Contributors will know what to fix first, reviews will move faster, and other reviewers will copy the pattern.

The system works because it forces one decision upfront: is this blocking or not? Make that decision explicit, and stop guessing.

The problem

An engineer adds a new configuration property:

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

They deploy it and forget to update the docs.

Three weeks later, a user reads the documentation. There’s no mention of retryAttempts, so they assume the feature doesn’t exist. Or worse, they assume the default behavior and it breaks their setup. A support ticket arrives.

This pattern repeats with every config change:

• Properties get added and docs lag behind.

• Properties get deprecated and docs still show them.

• Defaults change and docs show the old values.

The same thing happens with API parameters, CLI flags, environment variables, and 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, and generate code, docs, and everything else from it.

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 you generate server code, client SDKs, API documentation, examples, and interactive API explorers. The schema is your contract, and everything else derives from it.

There’s a second benefit. Decoupling the schema from the actual code makes it easier to have conversations about the contract itself. Teams can review and agree on the API structure before anyone implements it.

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 have to build the generators yourself, which can be a stopper when resources are tight.

Approach 2: Annotate your code

Add documentation as annotations directly in your code, and 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 the annotated code, you generate an intermediate schema and then 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, and stay consistent.

How to implement it

Start by documenting your source of truth. Write your schema file or add annotations to your code, including descriptions, types, defaults, and constraints. Be thorough here, because this is the single source that everything else generates from.

Then choose your generator. Check whether existing plugins work for your docs platform. Rendering OpenAPI in Docusaurus? There’s a plugin. Sphinx? There’s an extension. If you need something more specific, like TypeScript docs in Antora, you’ll need a custom solution.

One tip for the annotation approach: always generate an intermediate schema file (JSON or YAML) first. Don’t try to parse code annotations directly in your docs build.

Finally, add it to CI. On every commit, validate the source, regenerate the documentation, and fail the build if validation fails. On merge, deploy the updated documentation automatically.

Start small

You don’t need to generate everything on day one. Start with one configuration file and generate just the reference table, keeping 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 across guides, and keep the step-by-step guides manual.

The result

An engineer adds a new parameter and 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, and 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 and 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, and update it whenever you catch the AI producing results that miss the mark.

Use it for docs, marketing copy, support responses, tutorials, 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 and 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 the product.

Worth the 30 minutes to set up.

Here’s a typical configuration table:

Clean at first glance, but 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

Instead of cramming everything into cells, give each property its own block:

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 rich description lists by default, so you’ll likely need a plugin or a custom extension. It’s worth it for complex configurations, and 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 (two or three columns), short descriptions, and uniform properties where every row has the same fields.

Use description lists for complex properties with multiple options, long explanations, and properties with different fields, where some are required, some have defaults, and some have neither.

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

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

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

Use a design tool

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

When you need to export, you choose the 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 goes out of date, replace the base image and reuse your existing highlights and arrows instead of 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 won’t stop 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 every screenshot uses 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 the code, test it, import it into the docs. That’s the whole trick.