What should’ve been a quick 15-minute API hookup turned into a three-hour rabbit hole. The docs promised an easy ride—just five steps and you’re good to go. But now there’s a developer glued to their desk, staring down a wall of terminal errors, Slack lighting up with questions, and the deadline inching out of reach.
“Whoever wrote this never actually used it,” they DM their team lead.
They’re not wrong. The guide was clean, structured, and covered all the parameters, except for one thing that developers actually needed: how the API behaves with nested objects once it reaches a real production environment.
This scene repeats daily across tech companies. Stack Overflow's 2023 Developer Survey found developers waste nearly a quarter of their coding time deciphering documentation, with 63% of all respondents spending more than 30 minutes a day searching for answers or solutions to problems.
Not because the writing is poor, but because the writers have never written code.
The industry calls them unicorns—developers who can write, or writers who can code. If you're picturing a mythical beast that's equally comfortable with semicolons and Oxford commas, you're not far off.
...developers waste nearly a quarter of their coding time deciphering documentation.
Most developers can explain complex algorithms to computers, but freeze when asked to explain them to humans. Ask them about their weekend, and they'll respond with a binary "good" or "bad." Ask them about their code, and suddenly you're trapped in a 45-minute monologue about optimization techniques that somehow invoke their favorite anime.
Meanwhile, traditional technical writers craft beautiful prose about features they've never used, like food critics describing meals they've only seen in pictures. The result? Documentation that reads like poetry but helps like a chocolate teapot.
MongoDB faced this problem as well. With documentation that was comprehensive but fundamentally flawed, support issues piled up. Developer forums overflowed with desperate workarounds. The documentation team kept polishing sentences while developers kept muttering darkly, "...just reading the source code."
Then MongoDB tried something different. They started hiring developers who could write, rather than writers who were educated in technology. These unicorn technical writers brought their battle scars to the documentation, knowing which edge cases break things, which examples actually help, and which details matter in production. Most importantly, they can translate developer grunts into actual English.
These advancements reduced the time for new users to get started and also helped existing users resolve issues more efficiently, as evidenced by MongoDB's continued investment in intelligent developer tools. Developers even started linking directly to the enriched documentation in forums, replacing the old "RTFM" refrain with meaningful guidance, signaling a shift toward a more collaborative developer community.
They started hiring developers who could write instead of writers who could learn tech.
Living in Both Worlds
At GitHub, technical writers do more than write—they code, too. They run into the same bugs they’re documenting. They work with the tools they write about. So when a developer flags a gap in the docs, these writer-devs know exactly where that frustration is coming from—and how to turn it into something useful.
GitHub has been leveling up its documentation game by treating it like code. That means things like automated tests for API documentation aren’t theoretical—they are built and run by the same people writing the documentation. And in the process, those folks often uncover edge cases or quirks that you’d never spot just skimming through a spec sheet.
Because they’re building against the real API, not just describing it, the docs end up reflecting how things actually work—not just how they’re supposed to work.
The companies that truly excel at documentation have something in common: they’ve found those rare unicorns who can speak both human and machine. These writer-developers write the docs, then dive into the code themselves. The line between coding and explaining disappears, and in its place are people who can actually have a conversation about both worlds.
Sure, this approach costs more. Developer-writers don’t come cheap. They might take longer to write up features because they thoroughly test everything they put down, ensuring it works in the real world. But in the long run, they pay off. They catch issues early, ease the load on support teams, and save developers from feeling like they need to change careers after reading some soul-crushing documentation.
The best technical writers aren’t just writers who understand tech. They’re developers who remember what it’s like to stare at broken code and wish someone had warned them about the gotchas. These unicorns might be rare, but they’re worth the search. Just don’t expect them to look you in the eye during the interview—they’ll be too busy staring at the code.
At DevDocs, we specialize in connecting you with developer-writers fluent in code, tools, and user needs. Our unicorns don’t just document—they transform documentation into a competitive edge. By leveraging our team-based approach, you receive expertise, reliability, and results that will elevate your product and brand. Ready to discover your unicorn? Contact us today.
Harness the power of a technical writing team with deep development experience. Reach out for a quote.
Or schedule a discovery call now
One of our Customer Success Managers will get in contact with you immediately about next steps on getting your project started!
.svg)
.svg)
.png)
