Slow builds were killing our docs
How we cut a Sphinx build from 30 minutes to under 3 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 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 30-minute 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.
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 400-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. The HTML build finishes in under a minute. The PDF build takes longer, but it doesn’t block the HTML output anymore. Writers can preview their changes immediately while the PDFs generate in the background.
The result
Build time dropped from 30 minutes to under 3 for most changes. That’s a 90% reduction.
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 add up
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.