Category: Developer Docs

Imagine two developers sitting down with the documentation for SuperForms, a fictional SaaS product that promises to handle the “backend nastiness” of web forms with a single API call. SuperForms has invested real effort into its docs: a clean quickstart, SDKs for six languages, and a sleek REST API walkthrough.

Sam (The Senior) opens the quickstart, skims the authentication section, copies a curl command to test the endpoint, and has form submissions hitting her backend within twenty minutes. She finds the docs “refreshingly concise” and rates them a 9/10.

Jamie (The Junior) opens the exact same page. He reads the authentication section three times, unsure if his API key belongs in the frontend code or a backend script. He pastes the initialization snippet, gets a 422 Unprocessed Entity error, and spends the next two hours on Stack Overflow because the docs didn’t explain what a 422 meant in this context. Jamie finds the docs “incomplete and elitist.” He rates them a 3/10.

They read the same words. They had completely different experiences.

The “Curse of Knowledge” at Work

This gap stems from a cognitive bias known as the Curse of Knowledge. Once you understand a complex concept (like the difference between client-side and server-side execution), it becomes almost impossible to remember what it felt like not to know it.

For the Senior, a sentence like “Store your API key as an environment variable” is a helpful shorthand. For the Junior, that same sentence is a wall. It assumes three hidden prerequisites:

1. What an environment variable is.
2. How to set one in their specific OS or deployment environment.
3. How to reference that variable in their code without leaking it to the browser.

When docs skip these “obvious” steps to remain “clean,” they aren’t being minimalist—they are being exclusionary.

Finesse: How to Write for Both Audiences

Writing for both Sam and Jamie simultaneously isn’t just a courtesy; it’s a hallmark of elite technical documentation. You don’t have to “dumb down” the content for seniors to help the juniors. You just need to use Progressive Disclosure.

Here are four strategies to bridge the gap:

1. The “Prerequisite Map” (With Escape Hatches)

Never assume your reader has their environment configured. At the top of your SuperForms quickstart, include a “Before You Begin” box.

• The Finesse: List the required skills (e.g., Node.js, .env files, Promises). Use aggressive hyperlinking. If Jamie doesn’t know what a Promise is, he can click the link to a “Conceptual Guide.” Sam will ignore the box entirely and keep scrolling.

2. The “Why” Toggle

Seniors want the What (the code). Juniors need the Why (the logic).

• The Finesse: Provide the code snippet prominently. Immediately below it, use a collapsible <details> tag labeled “How this works under the hood.” Inside, explain the request-response cycle or why a specific header is required. This keeps the main flow “fast” for Sam while providing a safety net for Jamie.

3. Write Error Docs for the “Person in the Dark”

Most API references list error codes like a dictionary: 401: Unauthorized. This is useless to a junior who thinks they are authorized.

• The Finesse: Effective troubleshooting guides explain why the error usually happens (e.g., “You might be using your Test Key in a Production environment”) and provide the “First Step” to fix it. Writing for someone who has never seen the error before is the highest-value investment a tech writer can make.

4. Contextualize the “Floating Snippet”

A floating code snippet is a trap. If you show a SuperForms configuration object, show where it lives in a standard project structure.

• The Finesse: Use small annotations or a file-tree visual (e.g., src/api/submit.js). Simply stating, “You should see a ‘Success’ message in your terminal,” closes a feedback loop that seniors close in their heads automatically, but juniors often second-guess.

The Bottom Line: Empathy is a Technical Skill

The technical writer who treats “developers” as a monolith is, without meaning to, building a wall in the middle of their product.

Great documentation meets developers where they are, whether they are six months or sixteen years into their career, and helps them get somewhere better. It takes discipline to ask: “Who might not follow this, and what is the smallest thing I can provide to help them keep up?”

That question is the difference between a doc that is “pretty” and a doc that is useful.

In my years as a technical writer at Google, Grafana Labs, and other employers, I’ve encountered several misconceptions about what technical writers actually do. Some stakeholders view us as glorified clerical support. Others expect us to be senior-level software engineers while maintaining documentation.

The reality is far more nuanced: we are specialized bridge-builders who manage the high-stakes intersection of human language and machine logic. We operate in the gap between what engineers know and what developers need to learn, transforming tribal knowledge into usable education.

Here are the 3 most common myths I’ve encountered about technical writing, what the role actually entails, and why getting this right matters.

Myth 1: Technical Writers Are “Information Secretaries”

The Misconception: Technical writers wait for engineers to send over notes, then simply reformat those notes into documentation. We’re basically human content management systems.

The Reality: This “secretary” approach produces fragmented, contradictory, and low-quality content. Real technical writing involves investigative research, information architecture, audience analysis, and strategic content design.

What the Work Actually Looks Like

Professional technical writers don’t passively wait for information. Instead, we:

• Embed ourselves in development cycles, attending sprint planning and standups to understand what’s being built and why
• Conduct structured interviews with SMEs, asking targeted questions that uncover not just what features do, but why they exist and how they fit into the broader ecosystem
• Analyze documentation gaps by reviewing support tickets and user feedback to identify where developers actually struggle
• Create information architectures that map content to user journeys, ensuring developers find answers through intuitive navigation
• Establish content standards that ensure consistency across teams

Good technical writers architect knowledge systems that serve multiple audiences simultaneously. This is why asking engineers to “write down what they built” produces documentation with no coherent learning path.

Myth 2: The Technical Writer Must Write Every Line of Code

The Misconception: A good technical writer should independently write all code samples, from basic examples to complex production implementations.

The Reality: While I maintain working knowledge of some languages, enterprise software is often too complex for a single writer to generate all code samples. Instead, my role is better described as a Technical Director who orchestrates high-quality examples.

The Technical Director Model

1. Identify the Use Case

Engineers want to document what they built; users need to understand how to solve problems. I translate between these perspectives:

• Engineer thinking: “We added support for custom retry policies”
• User thinking: “How do I make my API calls more resilient to network failures?”

2. Enlist the Right Resources

I identify which engineer has the deepest knowledge of a subsystem, who writes clean example code, and who has bandwidth to contribute.

3. Verify, Refine, and Test

Raw code from engineers rarely ships as-is. My review includes:

• Compilation and execution testing: Does it actually work?
• Security review: Are we showing unsafe patterns?
• Readability optimization: Removing complexity, adding explanatory comments
• Error handling: Ensuring examples show realistic error handling, not just happy paths

4. Maintain and Update

I track which code samples are affected by breaking changes, coordinate updates before deprecated features are removed, and maintain automated testing for critical examples.

When Technical Writers Do Write Code

For simpler examples, I may write the code myself. But attempting to write complex, production-representative code for unfamiliar systems wastes time and produces fragile examples.

Myth 3: Engineers Can Simply Replace Technical Writers

The Misconception: Documentation is just “writing stuff down.” Any engineer with decent communication skills can handle it, eliminating the need for dedicated technical writers.

The Reality: While some engineers are excellent writers, systematically replacing technical writers introduces profound risks. This isn’t about engineers lacking capability—it’s about specialization, incentives, and the invisible complexity of documentation as a discipline.

The Commitment Gap

An engineer’s primary work is building features and fixing bugs. Documentation becomes a secondary concern, creating predictable patterns:

• Documentation written only when forced by PR requirements
• Stale documentation when APIs change but docs don’t get updated
• Inconsistent styles across different engineers’ contributions
• Coverage gaps where exciting features get documented but essential operational concerns don’t

The Curse of Knowledge

Engineers suffer from unconsciously assuming others share their background knowledge. Here’s what this looks like:

Engineer-written documentation:

Configure the service mesh egress gateway to handle external traffic.

Technical writer-written documentation:

Before your application can make requests to external APIs, you need to configure the service mesh to allow outbound traffic. In Joeware, this requires creating an Egress Gateway...

The engineer’s version isn’t wrong, but it assumes you know what a service mesh is, what “egress” means, and where configuration happens. Technical writers are trained to identify implicit assumptions, sequence information to build from foundational concepts, and anticipate failure modes.

The Reality: A Partnership of Specialists

The most effective documentation emerges from genuine partnerships where:

• Engineers provide deep technical expertise about how systems work
• Technical writers provide audience expertise about how developers learn and where they struggle
• Both groups review each other’s work to catch technical errors and pedagogical gaps

When documentation is treated as a first-class citizen of the engineering process, organizations see measurable results:

• Lower support costs: Developers self-serve answers
• Faster onboarding: New users become productive in hours instead of days
• Better product decisions: Explaining features often reveals UX problems before launch
• Competitive advantage: Documentation quality often determines which product wins

What “Good” Looks Like

Technical writers aren’t a luxury. We’re strategic investments in product success, developer experience, and sustainable growth. Good documentation teaches developers to think in your product’s paradigm, anticipates their struggles, and makes the complex feel achievable.

That’s not something you get by asking engineers to write more clearly. It’s something you get by respecting technical writing as the specialized craft it is.