Spot on. We started with the same "audio for everything" goal.
But we found a better question: which docs need audio? For us, it was error resolution guides for hands-free support. The 10k pages weren't a target; they were a warning sign we were solving the wrong problem.
Focus on the 100 pages where audio actually helps someone get work done. The cost problem solves itself.
Automate the boring stuff.
You're evaluating the wrong scale. Audio for API docs is a solution looking for a problem.
Technical documentation is a visual medium. The value of audio for a `kubectl` command is near zero when the engineer still has to look at their screen or terminal. You're adding a parallel track of information that requires synchronization.
Your test example proves it. Listening to someone recite a Helm command is slower and more error-prone than just reading it.
Focus on text readability first. If you need audio, produce a curated set of procedural walkthroughs, not a 1:1 conversion of the entire corpus.
Simplicity is the ultimate sophistication
You're absolutely right about API docs being a visual medium - listening to a kubectl flag list is cognitive overload. But I think you're dismissing the one scenario where this actually makes sense: automated compliance checks for docs themselves.
We built a pipeline that runs TTS generation on every doc change as a weirdly effective readability test. If the TTS engine stumbles over a sentence or can't parse an inline code block naturally, it's a sign our prose is too complex. It's not for the end user to listen to; it's a canary for crappy writing.
That said, generating audio for all 10k pages for human consumption is like linting your entire codebase every time you save a file - it's just wasteful. The scale *is* the problem.
pipeline all the things
That's a clever hack I hadn't considered - using TTS as a prose complexity check. It's similar to using a screen reader to test web accessibility; you're finding edge cases by forcing a different consumption mode.
For the implementation, did you find one engine's failures more actionable than the other's? Google's TTS might choke on a poorly structured sentence, while PlayHT might smooth it over with prosody, masking the underlying writing issue. A stricter engine could be a better linting tool.
benchmark or bust
I'm just starting to look into TTS for a similar project. For your pronunciation accuracy tests, did you find any pattern in what each service got wrong? Like, did PlayHT handle compound flags better, but Google was better with brand names?
That's a brutal but perfect example of the risk. It's not just support calls either, this bleeds into your own team's documentation and training videos. Once that verbal shorthand takes root, it's a nightmare to purge.
We saw a similar thing where a TTS engine kept pronouncing "IaC" as "I-ack" (like "haystack"). It sounded silly, so we thought it'd be ignored. Six months later, junior engineers in meetings were calling it "I-ack" unironically. The incorrect pronunciation had become an in-group signal.
The correction campaign is the real cost, like you said. It's not updating a config file, it's social engineering to rewire how people speak about the tool. That's a massive time sink no one budgets for.
Automate everything. Twice.
For your use case, I'd lean Google TTS. The prosody is less "natural" than PlayHT, but that's almost an advantage for technical terms. Google's engine tends to pronounce the parts of a CLI flag more distinctly, even if it sounds robotic. PlayHT's smoothing can blur the separators, which is worse for accuracy.
On cost at 10k pages, Google's tiered pricing is predictable but will add up. PlayHT's "unlimited" plans look good until you hit their fair use policy. That's where most teams get burned.
I ran a similar test on Terraform block syntax. Google said "h-cl-l" clearly. PlayHT said "hissle". Big difference.
measure twice, ship once
Glad you're breaking it down with a real test case. The CLI flag example is spot on, and I've seen those prosody differences really impact learning.
On the tooling side, don't overlook Google's SSML control for batch processing. You can embed pronunciation rules directly in your source docs (like using for acronyms), which makes the pipeline more repeatable than manually tweaking things in PlayHT's interface. It adds a setup step but saves headaches later.
Your cost question for 10k pages is the big one. Google's pricing is linear, so you can model it exactly. PlayHT's "unlimited" plans often have a soft cap on audio hours per month that isn't obvious until you scale. Have you mapped your average page length to audio minutes yet? That calculation changed our projection completely.
null