Why Document Generation Tools Don't Solve Documentation
Another week, another documentation tool trending on Hacker News. This time it's Pandoc templates, as Hacker News reported, promising to make document generation easier with pre-built layouts for everything from academic papers to technical specifications.
But here's the thing: we don't have a document generation problem. We have a documentation culture problem.
I've worked with dozens of engineering teams through AgileStack, and the pattern is always the same. They spend weeks evaluating tools like GitBook, Notion, Confluence, or now Pandoc templates. They get excited about features like automated PDF generation, beautiful themes, or seamless Git integration. Then six months later, their documentation is still garbage.
The tools aren't the bottleneck. The process is.
The Real Documentation Problem
Last month we worked with a fintech startup that had implemented a beautiful documentation pipeline. Markdown files in Git, automated builds with Pandoc, gorgeous PDFs generated on every merge. The CTO was proud of the setup.
Their actual documentation? Three outdated API guides, a README that hadn't been updated since 2022, and a getting-started guide that referenced Docker images that no longer existed.
They had solved the "how do we make docs look good" problem while completely ignoring the "how do we make sure docs exist and stay current" problem.
This is what every documentation tool misses. The hard part isn't converting markdown to HTML. The hard part is getting Sarah from the backend team to update the authentication docs when she changes the JWT implementation. The hard part is making sure the deployment guide reflects the actual deployment process, not the one from three refactors ago.
Why Pandoc Templates Miss the Mark
Pandoc templates are technically impressive. You can generate professional-looking documents from markdown, with consistent styling, proper typography, and multiple output formats. The templates handle all the LaTeX complexity, giving you publication-quality PDFs without learning a typesetting language.
But who exactly is asking for publication-quality PDFs of their API documentation?
Most engineering documentation lives in three places: internal wikis that never get updated, README files that become outdated the moment someone pushes code, and the heads of the two developers who actually understand the system.
Adding beautiful PDF generation to this workflow is like putting racing stripes on a car that won't start.
What Actually Works for Engineering Documentation
The teams that have good documentation don't use fancy tools. They use boring tools with good processes.
Here's what we've seen work:
Documentation as Code Review Requirements
One client made documentation updates mandatory for any PR that changes public APIs. Not optional. Not "nice to have". If you modify an endpoint, you update the docs in the same PR, or it doesn't merge.
They use plain markdown files in the same repo as the code. No special tooling. No PDF generation. Just markdown files that live next to the code they document.
Their documentation is always current because updating it is part of shipping code, not a separate task that happens "when we have time".
Embedded Examples That Actually Run
Another team solved the "docs that lie" problem by making their examples executable. Every code snippet in their documentation is actually a test case that runs in CI.
If the API changes and breaks a documentation example, the build fails. This forces them to update docs when they change code, because broken docs break the build.
They use a simple script that extracts code blocks from markdown files and runs them against the actual API. Nothing fancy. It just works.
Documentation Ownership
The best-documented team we work with assigns documentation ownership the same way they assign code ownership. Each service has a docs owner who's responsible for keeping that service's documentation current.
It's not a separate role. It's part of being a senior developer on that team. When you own the user authentication service, you also own the authentication docs.
This creates accountability. When someone files a bug report about confusing authentication docs, it goes to the auth team lead, not to some mythical "documentation team" that doesn't exist.
The Template Trap
Pandoc templates represent a deeper problem in how we think about documentation. They assume the issue is presentation, not content.
This leads to what I call the template trap: spending time making bad documentation look good instead of making good documentation exist.
I've seen teams spend a month perfecting their documentation build pipeline, then discover they have nothing worth documenting. Or worse, they have comprehensive docs that are six months out of date.
Beautiful, outdated documentation is worse than ugly, current documentation. At least ugly docs signal that they might be wrong. Beautiful docs make you trust them, even when they're lying.
When Document Generation Actually Helps
There are cases where tools like Pandoc templates solve real problems. If you're writing technical specifications that need to be shared with external partners, PDF generation makes sense. If you're creating compliance documentation that needs specific formatting, templates help.
But these are edge cases for most engineering teams. Most internal documentation doesn't need to be pretty. It needs to be accurate, findable, and current.
The best documentation tool is the one your team will actually use consistently. For most teams, that's markdown files in Git, maybe with a simple static site generator like Jekyll or Hugo.
Building Documentation Culture, Not Pipelines
Instead of evaluating new documentation tools, here's what actually improves your docs:
Make documentation updates part of your definition of done. If a feature isn't documented, it's not complete.
Review documentation in code review. Treat docs changes like code changes. They need the same level of scrutiny.
Measure documentation quality. Track how often docs lead to successful task completion, not how pretty they look.
Assign ownership. Every piece of documentation should have an owner who's responsible for keeping it current.
Start small. Don't try to document everything at once. Pick the three most important workflows and document those well.
What This Means for Your Team
Before you implement another documentation tool, ask yourself: do you have a tools problem or a process problem?
If your team consistently updates documentation but struggles with formatting or generation, maybe Pandoc templates help.
If your documentation is sparse, outdated, or ignored, no tool will fix that. You need process changes, not better PDF generation.
The goal isn't beautiful documentation. The goal is documentation that helps your team ship faster and onboard new developers effectively. Focus on that, and the tools become much less important.
Most engineering teams would be better served by a simple markdown-in-Git workflow with strong process enforcement than by any fancy documentation pipeline. Start there. You can always add complexity later if you actually need it.
Building something in this space? AgileStack helps teams ship enterprise-grade software without the consulting-firm overhead. Book a 30-minute call and tell us what you're working on.