Slow builds were killing our docs
How we cut a Sphinx build from 30 minutes to under 5 by splitting PDFs into chapters and parallelizing outputs.
“Our docs build takes 30 minutes.”
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.