Code meets content: The era of the developer-writer hybrid

Three hours into a 15-minute API integration, a developer is still debugging. They've done everything the docs said. The integration still isn't working.

"Whoever wrote this never actually used it," they DM their team lead.

They're not wrong. The guide was clean and structured, covering all parameters except how the API behaves with nested objects in a real production environment. Stack Overflow's 2023 Developer Survey found developers waste nearly a quarter of their coding time deciphering documentation, with 63% spending more than 30 minutes a day searching for answers. The writing isn't always the problem. The writers are.

The unicorn hunt

The industry calls them unicorns: developers who can write, or writers who can code. Most developers can explain complex algorithms to computers but struggle to explain them to humans. Most traditional technical writers craft prose about features they've never used. The result is documentation that's readable but not useful, and developers who end up in the source code anyway.

The 2025 State of the Docs report captures the broader pressure behind this shift: documentation teams are being asked to support more complex products, more audiences, and AI-assisted experiences without sacrificing trust or accuracy.

Getting developers to give a darn

MongoDB ran into this directly. With documentation that was comprehensive but fundamentally flawed, support issues piled up and developer forums filled with workarounds. The documentation team kept polishing sentences while developers kept muttering that they were just reading the source code.

MongoDB changed course by hiring developers who could write rather than writers with technical backgrounds. They knew which edge cases break things, which examples actually help in production, and which details matter when something goes wrong.

The result was faster onboarding for new users and fewer issues for existing ones, reflected in MongoDB's continued investment in developer tooling. Developers started linking directly to the documentation in forums rather than posting workarounds, which is a meaningful signal that something changed.

Living in both worlds

GitHub's technical writers work directly in the codebase. They hit the same bugs they document, which means when a developer flags a gap, they already know where it came from. At GitHub, API documentation is tested alongside the product. When an example breaks, or a change introduces unexpected behavior, teams can catch it before the documentation reaches users. GitHub's own content design principles show how closely the writing practice is tied to the product experience.

Where to find unicorns

The companies that produce the best documentation have found people who can work in both worlds. These writer-developers write the docs, then test what they've written in the actual product. The line between coding and explaining disappears, replaced by practitioners who can have a credible conversation about both.

This approach costs more. Developer-writers take longer to document features because they test everything they put down: they're not describing behavior, they're verifying it. But the return is real. Good documentation requires both writing ability and technical understanding.

Documentation needs its own person: someone whose job is knowing the product as well as the people who built it, without being so close to it that they've stopped seeing where it breaks down. Writers who understand the codebase catch the gaps that spec sheets miss. See how we approach developer documentation.