How to become a Technical Writer / Developer Advocate

A complete, honest roadmap for two related roles: technical writing, centred on clear documentation, and developer advocacy, centred on community and reach. It covers where they overlap and where they diverge, from technical literacy and writing through docs, code samples, community, talks, and AI. It runs top to bottom, foundational to advanced, so you always know what comes next. Free to read, no signup required.

1. 01

   Step 01Two related roles: how they overlap and differ

   Technical writing and developer advocacy are close cousins, and this roadmap covers both. They share a foundation but pull in different directions, so it helps to be clear about which you’re aiming for.

   • What they share: Both explain technical products clearly to a technical audience, and both need real writing skill and genuine understanding of the technology.
   • The technical writer: Centres on documentation: accurate, well-structured, maintainable writing that helps people use a product. Precision and clarity are the craft.
   • The developer advocate: Centres on community and advocacy: talks, demos, code samples, and being a two-way bridge between developers and the product team. Reach and relationships are the craft.
   • A spectrum, not a wall: Many people do a mix, and one can lead to the other. Later steps here note which role each skill leans toward.

   A quick way to tell them apart: a technical writer is judged mostly on how good the documentation is, while a developer advocate is judged mostly on developer trust, adoption, and community. The overlap is real, but the centre of gravity differs.

   Technical writingDeveloper advocacyOverlapWhere they differ
2. 02

   Step 02Technical literacy

   You can’t explain what you don’t understand. Both roles need enough technical depth to use a product like the audience does and to speak credibly to developers.

   • Understanding the product: Learning a technical product deeply enough to use it, hit its rough edges, and explain it honestly.
   • Reading and writing code: Enough programming to follow code, run examples, and write working samples, which matters more for advocacy.
   • How software fits together: APIs, the command line, and how developers actually work, so your explanations match their reality.
   • Learning fast: Getting up to speed on new tools quickly, since both roles constantly meet unfamiliar technology.

   Product depthReading codeAPIs & CLIDeveloper workflowsFast learning
3. 03

   Step 03Writing clearly

   Clear writing is the shared core skill, and it is harder than it looks. Both roles live or die on the ability to make complex things simple without making them wrong.

   • Clarity and structure: Writing so a reader gets it in one pass, with structure that lets them find what they need.
   • Audience awareness: Writing for the reader’s actual level, from a first-time user to an expert, rather than for yourself.
   • Simple, not dumbed down: Removing jargon and fluff while keeping the technical content accurate and complete.
   • Editing: Cutting and rewriting, since strong writing is mostly good editing.

   The hardest part of technical writing is making something simple without making it false. Clear, accurate, honest writing is a genuine skill that takes deliberate practice, whichever role you pursue.

   ClarityStructureAudiencePlain languageEditing
4. 04

   Step 04Documentation types & structure

   Documentation is the technical writer’s core output and a big part of advocacy too. Different jobs need different kinds of docs, and knowing which is which is a real skill.

   • The main doc types: Tutorials, how-to guides, reference, and explanation each serve a different need, and mixing them up frustrates readers.
   • Getting-started guides: The first experience that decides whether a developer sticks with a product or gives up.
   • API reference: Accurate, complete reference that developers can trust, often the most-used docs of all.
   • Information architecture: Organising docs so people can find what they need, which matters as much as the writing itself.

   TutorialsHow-to guidesReferenceExplanationGetting startedDoc structure
5. 05

   Step 05Docs tooling & docs-as-code

   Modern documentation is built with developer tools. Comfort with docs-as-code makes a technical writer far more effective and self-sufficient.

   • Markdown & static sites: Writing in Markdown and publishing with documentation site generators, the common modern setup.
   • Git and review: Treating docs like code: versioned, reviewed in pull requests, and living beside the product.
   • Keeping docs current: Building habits and checks so documentation doesn’t drift out of date as the product changes.
   • Diagrams and screenshots: Using visuals well, and keeping them maintainable rather than instantly stale.

   MarkdownDocs-as-codeGitStatic site generatorsKeeping docs fresh
6. 06

   Step 06Developer empathy & code samples

   Great developer content comes from genuinely understanding developers. Working code samples are where that empathy becomes concrete, and they lean more toward advocacy.

   • Thinking like a developer: Understanding the frustrations, goals, and shortcuts of the people you serve, so your work fits how they work.
   • Working code samples: Writing examples that actually run and that a developer can copy, adapt, and trust.
   • Sample projects and demos: Building small end-to-end examples that show a product in a realistic context.
   • Meeting developers where they are: Delivering help in the formats and places developers actually look, not only a docs site.

   Nothing loses developer trust faster than a code sample that doesn’t run. Whether you write docs or advocate, working, tested examples are the fastest way to earn credibility.

   Developer empathyWorking samplesDemo projectsCopy-paste ready
7. 07

   Step 07Community & advocacy

   This is the heart of developer advocacy and where it diverges most from technical writing. Advocacy is about relationships, reach, and being a two-way bridge.

   • Engaging a community: Answering questions, helping developers succeed, and building genuine relationships rather than broadcasting.
   • Being a two-way bridge: Carrying developer feedback back to the product team, which is a defining part of the advocate role.
   • Public speaking: Giving talks, demos, and workshops at meetups and conferences, a core advocacy skill writers rarely need.
   • Authenticity: Earning trust by being genuinely helpful and honest, since developers quickly tune out marketing.

   CommunityTwo-way feedbackPublic speakingConferencesAuthenticity
8. 08

   Step 08Content beyond docs

   Both roles create content, but advocates especially work across many formats. Reaching developers means meeting them in blogs, videos, and talks, not only documentation.

   • Blog posts and tutorials: Writing content that teaches and draws developers in, beyond the reference docs.
   • Video and streams: Explaining and demoing on video, an increasingly important advocacy format.
   • Talks and workshops: Turning knowledge into sessions that teach a room or a conference audience.
   • Choosing the format: Matching the format to the message and the audience, rather than defaulting to one medium.

   BloggingVideoTalksWorkshopsFormat choice
9. 09

   Step 09Feedback loops & impact

   Both roles improve the product, not only describe it. Closing the loop with the product team and showing impact is what makes the work valued.

   • Surfacing pain points: Noticing where developers struggle, in docs or in the product, and getting those fixed.
   • Improving the product: Feeding real developer friction back to engineering and product, since you often see it first.
   • Measuring impact: Showing how docs and advocacy affect adoption, support load, and developer satisfaction.
   • Working across teams: Partnering with product, engineering, and marketing to make developer experience better.

   Feedback loopsDeveloper experienceImpact metricsCross-team work
10. 10

    Step 10Building a portfolio & career

    Both roles are shown, not only claimed. A body of public work is how you demonstrate you can explain technology and reach developers.

    • A public body of work: Docs you’ve written, posts you’ve published, or talks you’ve given, since this work is naturally visible.
    • For writers: Sample documentation and clear writing that shows structure, accuracy, and audience awareness.
    • For advocates: Talks, videos, code samples, and community presence that show reach and developer trust.
    • Building in public: Sharing what you make and learn, which is both practice and portfolio.

    These roles reward people who make their work public. A single strong tutorial, doc set, or talk you can point to is worth more than a resume line, because it directly shows the skill.

    Public workWriting samplesTalks & videosBuilding in public
11. 11

    Step 11AI & the modern writer/advocate

    AI is changing how technical content is made and how developers find answers. Used well it speeds up drafting; the judgement, accuracy, and trust still come from you.

    • AI in the workflow: Using AI to draft, outline, and edit faster, while you verify every technical detail and keep the voice human.
    • Docs for AI consumption: Writing clear, structured docs, which now also helps AI assistants answer developer questions correctly.
    • Explaining AI products: Documenting and advocating for AI tools, whose non-deterministic behaviour needs careful, honest explanation.
    • Accuracy over speed: Never shipping AI-drafted technical content unchecked, since a confident wrong instruction erodes trust fast.

    AI can draft content quickly, which raises the value of what it can’t reliably do: verifying accuracy, understanding the audience, and earning developer trust. Those remain the core of both roles.

    AI draftingDocs for AIExplaining AI productsAccuracy