# I'd Rather Be Writing

> A technical writing blog and course site by Tom Johnson, a technical writer in the Seattle area (currently at Google, previously Amazon). Running since 2006, the site covers technical communication, API documentation, AI-assisted documentation workflows, and the practice and profession of tech comm. It combines a long-running blog (2594 posts) with several free, book-length courses.

The site has two kinds of content:

- **Courses** — structured, sequential, book-length material that is revised over time. The API documentation course and the AI courses are the main ones. These are the most substantive and most frequently updated parts of the site.
- **Blog posts** — dated essays and observations going back to 2006. Older posts reflect the tools and assumptions of their moment; check the date before treating a post as current guidance.

Content is authored in Markdown and published with Jekyll. Everything is free to read. Full text of every page is available at its URL; there is no paywall or login.

## Start here

- [Home / latest blog posts](https://idratherbewriting.com/): Reverse-chronological list of recent posts
- [About Tom Johnson](https://idratherbewriting.com/aboutme/): Background, career, and what this blog covers
- [Documenting APIs course](https://idratherbewriting.com/learnapidoc/): A 17-chapter course on writing API documentation, with hands-on activities
- [AI courses hub](https://idratherbewriting.com/ai/index.html): Three self-contained courses on AI and technical communication
- [Series index](https://idratherbewriting.com/series/): Multi-part post series grouped by topic
- [All posts by year](https://idratherbewriting.com/all/): Complete archive of every post

## Documenting APIs course

A free, book-length course on API documentation for technical writers and engineers. Covers REST API concepts, using an API like a developer, documenting endpoints, the OpenAPI specification, testing docs, conceptual topics, code tutorials, publishing, and career topics. Includes hands-on activities against real APIs.

- [Course overview](https://idratherbewriting.com/learnapidoc/docapis_overview.html): This section provides a high-level, detailed overview for the API documentation course. I introduce the goals of the course, explain why I developed it, tell you a bit about myself, provide some recordings, slides, an...
- [Chapter 1: Introduction to REST APIs](https://idratherbewriting.com/learnapidoc/docapis_introtoapis.html): What REST APIs are, how they differ from SOAP, and why documentation matters so much here.
- [Chapter 2: Using an API like a developer](https://idratherbewriting.com/learnapidoc/likeadeveloper.html): Get API keys, make requests with curl and Postman, and work with the JSON that comes back.
- [Chapter 3: Documenting API endpoints](https://idratherbewriting.com/learnapidoc/docendpoints.html): The five sections of reference documentation, from resource descriptions to response schemas.
- [Chapter 4: OpenAPI spec and generated reference docs](https://idratherbewriting.com/learnapidoc/restapispecifications.html): Describe your API with OpenAPI, then publish it using Stoplight, Swagger UI, or Redocly.
- [Chapter 5: Step-by-step OpenAPI code tutorial](https://idratherbewriting.com/learnapidoc/openapi_tutorial.html): Hand-code an OpenAPI specification object by object, using the Swagger Editor.
- [Chapter 6: Testing API docs](https://idratherbewriting.com/learnapidoc/testingdocs.html): Test your documentation against the real API so the instructions actually work.
- [Chapter 7: Conceptual topics in API docs](https://idratherbewriting.com/learnapidoc/docconceptual.html): Overviews, getting-started guides, authentication, status codes, rate limits, and glossaries.
- [Chapter 8: Code tutorials](https://idratherbewriting.com/learnapidoc/docapiscode.html): Approaches for documenting code samples and tutorials — the hardest part for non-engineers.
- [Chapter 9: The writing process](https://idratherbewriting.com/learnapidoc/writing_process.html): Planning, interviewing engineers, drafting, reviewing, and shipping developer documentation.
- [Chapter 10: Publishing API docs](https://idratherbewriting.com/learnapidoc/publishingapis.html): Structure, templates, branding, and the conventions that make developers trust your docs.
- [Chapter 11: Publishing tools](https://idratherbewriting.com/learnapidoc/publishingtools.html): Docs-as-code workflows using Git, GitHub, Jekyll, and other publishing toolchains.
- [Chapter 12: Thriving in the API doc space](https://idratherbewriting.com/learnapidoc/jobapis.html): Getting hired: the coding familiarity, portfolio, and writing samples employers look for.
- [Chapter 13: Library-based APIs](https://idratherbewriting.com/learnapidoc/nativelibraryapis.html): Documenting Java and C++ libraries that developers compile in rather than call over the web.
- [Chapter 14: Processes and methodology](https://idratherbewriting.com/learnapidoc/docapis_managing_doc_processes.html): Managing doc work with Scrum-like processes, bug tracking, and review workflows.
- [Chapter 15: Metrics and measurement](https://idratherbewriting.com/learnapidoc/docapis_metrics_and_measurement.html): Measuring documentation quality and tracking improvement in ways management believes.
- [Chapter 16: Glossary](https://idratherbewriting.com/learnapidoc/glossary_overview.html): More than 130 defined terms spanning API concepts, tooling, and documentation practice.
- [Chapter 17: Additional resources](https://idratherbewriting.com/learnapidoc/resources.html): Supplementary material: GraphQL, RAML, API Blueprint, and topics beyond the core course.

## AI and technical communication

Three self-contained courses. They don't build on each other. Written at different times, tracking the field's progression: use cases (2023), prompt engineering (2024), agent skills (2025-2026).

- [AI courses hub](https://idratherbewriting.com/ai/index.html): Overview of all three courses and how they fit together
- [AI Book Club](https://idratherbewriting.com/ai-book-club/): Notes and discussion on books about AI
- [All AI-related blog posts](https://idratherbewriting.com/category-ai/): Dated posts on AI and tech comm

### Course: Agent skills

Building reusable instruction files that program an AI agent to handle repeatable documentation tasks. Includes a chapter on product skills — skills that route AI agents through your product's docs.

- [Overview](https://idratherbewriting.com/ai/skills.html)
- [Getting set up: editor, models, and environment](https://idratherbewriting.com/ai/skills-setup.html)
- [When to build a skill](https://idratherbewriting.com/ai/skills-when-to-build.html)
- [Skill structure and creation](https://idratherbewriting.com/ai/skills-structure-creation.html)
- [Where to store and invoke skills](https://idratherbewriting.com/ai/skills-storage-invocation.html)
- [Modularity of skills](https://idratherbewriting.com/ai/skills-modularity.html)
- [Design principles for skills](https://idratherbewriting.com/ai/skills-design-principles.html)
- [Forking and sharing skills](https://idratherbewriting.com/ai/skills-forking-sharing.html)
- [Testing a skill](https://idratherbewriting.com/ai/skills-testing.html)
- [Advanced patterns: subagents, loops, and reverse engineering](https://idratherbewriting.com/ai/skills-advanced-patterns.html)
- [Overview](https://idratherbewriting.com/ai/product-skills.html)
- [From developer experience to agent experience](https://idratherbewriting.com/ai/product-skills-agent-experience.html)
- [Problems with product skills](https://idratherbewriting.com/ai/product-skills-problems.html)
- [Roles for tech writers with product skills](https://idratherbewriting.com/ai/product-skills-tech-writer-roles.html)
- [Mining users' AI chat sessions: gaps and forensics](https://idratherbewriting.com/ai/product-skills-chat-analysis.html)
- [Reimagining the documentation experience](https://idratherbewriting.com/ai/product-skills-reimagining-docs.html)

### Course: Prompt engineering for tech comm scenarios

Prompting techniques worked out against scenarios technical writers actually face: meeting notes, release notes, code samples, templates, and more.

- [Overview](https://idratherbewriting.com/ai/prompt-engineering.html)
- [Task decomposition and complex tree diagrams](https://idratherbewriting.com/ai/prompt-engineering-task-decomposition.html)
- [Creating high-fidelity, thematically organized notes from engineering meetings using AI](https://idratherbewriting.com/ai/prompt-engineering-summarizing-meeting-notes.html)
- [Populating documentation templates using AI](https://idratherbewriting.com/ai/prompt-engineering-populating-documentation-templates.html)
- [Reverse engineering the recipe for excellent documentation](https://idratherbewriting.com/ai/reverse-engineering-prompts.html)
- [Gathering source material for context input](https://idratherbewriting.com/ai/prompt-engineering-source-material-context.html)
- [Error checking the AI output](https://idratherbewriting.com/ai/prompt-engineering-error-checking.html)
- [Creating scripts to automate doc build processes](https://idratherbewriting.com/ai/prompt-engineering-doc-build-scripts.html)
- [Using file diffs for better release notes in reference docs](https://idratherbewriting.com/ai/prompt-engineering-release-notes-reference-docs.html)
- [Automate links in your release notes using AI](https://idratherbewriting.com/ai/automating-linking.html)
- [Using long-token contexts to quality check an entire API doc set](https://idratherbewriting.com/ai/prompt-engineering-entire-doc-set-prompts.html)
- [Using AI to jump-start code samples](https://idratherbewriting.com/ai/prompt-engineering-code-samples.html)
- [From engineer interviews to written draft, with chain of thought reasoning](https://idratherbewriting.com/ai/prompt-engineering-iterative-chain-of-thought.html)
- [Using AI to design landing pages](https://idratherbewriting.com/ai/prompt-engineering-landing-pages.html)
- [Using AI to mine log messages from reference doc builds](https://idratherbewriting.com/ai/prompt-engineering-mine-log-messages.html)
- [Using AI with issue tracking systems](https://idratherbewriting.com/ai/prompt-engineering-issue-tracking-systems.html)
- [API quick reference guides](https://idratherbewriting.com/ai/prompt-eng-api-qrgs.html)

### Course: Use cases for AI

A survey of where AI genuinely helps with documentation work — summarizing, comparing, explaining code — and where it still falls short.

- [Overview](https://idratherbewriting.com/ai/use-cases.html)
- [Using AI in APIs: What works, what doesn't](https://idratherbewriting.com/ai/docapis_ai_what_works_and_doesnt.html)
- [Use cases for AI: Develop build and publishing scripts](https://idratherbewriting.com/ai/ai-tools-build-publish-api-docs.html)
- [Use cases for AI: Understand the meaning of code](https://idratherbewriting.com/ai/docapis_ai_learn_coding.html)
- [Use cases for AI: Distill needed updates from bug threads](https://idratherbewriting.com/ai/docapis_ai_fix_bugs.html)
- [Use cases for AI: Summarize long content](https://idratherbewriting.com/ai/docapis_ai_summaries.html)
- [Use cases for AI: Synthesize insights from granular data](https://idratherbewriting.com/ai/docapis_thematic_analysis.html)
- [Use cases for AI: Seek advice on grammar and style](https://idratherbewriting.com/ai/docapis_ai_language_advice.html)
- [Use cases for AI: Arrange content into information type patterns](https://idratherbewriting.com/ai/docapis_pattern_prompts.html)
- [Use cases for AI: Compare API responses to identify discrepancies](https://idratherbewriting.com/ai/docapis_ai_comparison_tasks.html)
- [Use cases for AI: Draft glossary definitions](https://idratherbewriting.com/ai/docapis_ai_glossary_definitions.html)

## Post series

Multi-part series written over the years. Each varies in length.

- [Reflections on Zen and the Art of Motorcycle Maintenance](https://idratherbewriting.com/zamm/why-reread-zen-and-art-of-motorcycle-maintenance.html)
- [Sitting, standing, and walking](https://idratherbewriting.com/blog/sitting-standing-walking-introduction/)
- [Trends to follow or forget](https://idratherbewriting.com/trends/trends-to-follow-or-forget-intro.html)
- [Journey away from smartphones](https://idratherbewriting.com/smartphones/overview.html)
- [A hypothesis about influence on the web and the workplace](https://idratherbewriting.com/web-and-workplace-influence/part1-introduction-to-influencers.html)
- [Mobility](https://idratherbewriting.com/blog/bike-commuting-from-renton-to-seattle/)
- [Reflecting seven years later about why we were laid off](https://idratherbewriting.com/blog/reflecting-seven-years-later-about-layoff-intro/)
- [Simplifying complexity](https://idratherbewriting.com/simplifying-complexity/index.html)
- [Value arguments for docs and tech comm](https://idratherbewriting.com/2017/12/28/value-of-tech-comm-in-company-part1/)
- [Visual communication](https://idratherbewriting.com/2016/03/12/new-series-on-visual-communication/)
- [Basketball](https://idratherbewriting.com/2018/04/19/why-watching-nba-can-make-you-a-worse-pickup-ball-player)
- [Biking](https://idratherbewriting.com/blog/biking-the-santa-clara-loop/)
- [Testing documentation](https://idratherbewriting.com/2015/07/07/testing-your-instructions/)
- [Voiceover techniques](https://idratherbewriting.com/2008/11/14/finding-a-conversational-voice-in-video-tutorials/)
- [Seven deadly sins of blogging](https://idratherbewriting.com/2009/09/15/seven-deadly-sins-of-blogging-1-being-fake/)
- [API documentation survey](https://idratherbewriting.com/2014/12/12/i-need-your-responses-to-my-api-documentation-survey/)
- [Author in DITA and Publish with WordPress](https://idratherbewriting.com/2013/01/21/how-to-import-webhelp-from-a-help-authoring-tool-into-wordpress/)
- [DITA journey](https://idratherbewriting.com/2014/04/16/my-dita-journey-begins/)
- [Dallas STC Summit videocasts](https://idratherbewriting.com/2010/05/11/a-few-ways-to-make-the-next-stc-summit-better/)
- [Get a Job in Technical Writing](https://idratherbewriting.com/2009/09/22/how-to-get-a-job-in-technical-writing-a-7-step-guide-for-students/)
- [Innovation in tech comm](https://idratherbewriting.com/2015/02/10/sustaining-and-disruptive-innovations/)
- [Jekyll versus DITA](https://idratherbewriting.com/2015/03/23/new-series-jekyll-versus-dita/)
- [Quick reference guides](https://idratherbewriting.com/2008/07/06/quick-reference-guides-the-poetry-of-technical-writing/)
- [Search engine optimization](https://idratherbewriting.com/2013/09/22/how-to-search-engine-optimize-your-help-content-or-documentation/)
- [User-centered documentation](https://idratherbewriting.com/2008/05/30/podcast-how-to-create-user-centered-documentation-interview-with-joe-sokohl/)
- [User-centered documentation principles](https://idratherbewriting.com/ucd-introduction/)
- [My journey to and from wikis](https://idratherbewriting.com/2012/06/11/essay-my-journey-to-and-from-wikis-why-i-adopted-wikis-why-i-veered-away-from-them-and-a-new-model-for-collaboration/)
- [Findability / organizing content](https://idratherbewriting.com/2010/05/17/new-series-organizing-content-organizing-content-1/)
- [From overlooked to center stage](https://idratherbewriting.com/2010/04/11/if-youre-in-atlanta-next-week-be-sure-to-check-out-currents/)
- [Java notes](https://idratherbewriting.com/java-introduction/)
- [JavaScript notes](https://idratherbewriting.com/javascript/)
- [DITA notes](https://idratherbewriting.com/ditaqrg/)

## Recent blog posts

- [Reflections on Ai4 conference - some absences from a tech writer's POV](https://idratherbewriting.com/blog/ai4-conference-reflections-tw) (2026-08-09): This week I attended Ai4, promoted as the largest AI conference in North America. It was held at The Venetian in Las Vegas and lasted 3 days. The conference had more than 12,000 attendees (from 100...
- [Orchestrating docs instead of writing them yourself — podcast with Sarah Deaton of Anthropic](https://idratherbewriting.com/blog/podcast-deaton-anthropic-tw-automation) (2026-08-02): In this podcast, co-host Fabrizio Ferri-Benedetti and I chat with Sarah Deaton, a technical writer at Anthropic who works on the Claude Code docs, about what documentation work looks like when much...
- [Building out a course on agent skills](https://idratherbewriting.com/blog/course-on-skills) (2026-07-21): I'm trying to build out a course on agent skills. For a while I've been looking for something more substantial and stable to sink my teeth into (similar to what I did with API documentation), and I...
- [The gap between academic and industry technical writing: What it is, why it exists, why it's important, and what we can do about it (Part II)](https://idratherbewriting.com/blog/gap-between-industry-and-academia-tw-part2) (2026-07-12): This is Part II of a guest post from Jeremy Rosselot-Merritt, an assistant professor at James Madison University. In this post, Jeremy transitions from describing the reasons for the gap between ac...
- [The gap between academic and industry technical writing: What it is, why it exists, why it's important, and what we can do about it (Part I)](https://idratherbewriting.com/blog/gap-between-industry-and-academia-tw-part1) (2026-07-12): This is a guest post from Jeremy Rosselot-Merritt, an assistant professor in the School of Writing, Rhetoric, and Technical Communication at James Madison University. In this post, Jeremy explains ...
- [Tom's opinionated guide to skill building 101](https://idratherbewriting.com/blog/all-about-skills-intro) (2026-06-30): The thing I'm most excited about with AI lately is SKILLs. (I have to capitalize the word at first so you know I'm talking about agent skills rather than just general capabilities; however, I'll su...
- [AI Book Club discussion of The Infinity Machine by Sebastian Mallaby](https://idratherbewriting.com/blog/book-club-infinity-machine-mallaby) (2026-06-28): This is a recording of the AI Book Club discussion of Sebastian Mallaby's The Infinity Machine: Demis Hassabis, DeepMind, and the Quest for Superintelligence. In the discussion, we talk about the c...
- [Judging beautiful docs, AI fatigue, and tool slop -- podcast with Fabrizio](https://idratherbewriting.com/blog/judging-beautiful-docs-ai-fatigue-podcast) (2026-05-31): In this podcast, I chat with Fabrizio Ferri-Benedetti about a variety of topics related to AI and docs, such as applying Italo Calvino's literary principles of lightness and quickness to evaluate d...
- [Review of Max Tegmark's 'Life 3.0: Being Human in the Age of Artificial Intelligence'](https://idratherbewriting.com/blog/book-review-tegmark-life-3-0-ai) (2026-05-17): This post is my review of Max Tegmark's Life 3.0, a book we read in the AI Book Club. Tegmark, an MIT physicist and founder of the Future of Life Institute, says Life 1.0 relies entirely on biologi...
- [AI Book Club discussion recording of 'Life 3.0: Being Human in the Age of Artificial Intelligence', by Max Tegmark](https://idratherbewriting.com/blog/book-club-tegmark-life-3-0) (2026-05-17): This is a recording of the AI Book Club discussion of Max Tegmark's Life 3.0: Being Human in the Age of Artificial Intelligence. Our discussion explores Tegmark's visions of superintelligence, the ...
- [Developing internal skills for recurring documentation processes like release notes](https://idratherbewriting.com/blog/internal-skills-release-docs) (2026-05-04): My hypothesis this year around AI was that if I develop some agent skills to speed up repeatable processes, it might clear up my bandwidth and free up time for me to work on non-repeatable doc task...
- [Looking back at the AI Book Club one year in](https://idratherbewriting.com/blog/looking-at-book-club-one-year-in) (2026-04-28)
- [On pace and value -- why is moving slow boring?](https://idratherbewriting.com/blog/pace-value-moving-slow-boredom) (2026-04-27)
- [Frenetic thinking](https://idratherbewriting.com/blog/frenetic-thinking-vs-careful-measured-analysis) (2026-04-26)
- [Work expands to fill the space allotted](https://idratherbewriting.com/blog/work-expands-to-fill-the-allotted-space) (2026-04-26)
- [Too much coffee?](https://idratherbewriting.com/blog/too-much-coffee) (2026-04-24)
- [AI Book Club discussion recording of 'Breakneck: China's Quest to Engineer the Future', by Dan Wang](https://idratherbewriting.com/blog/book-club-breakneck-china-wang) (2026-04-23): This is a recording of the AI Book Club discussion of Dan Wang's Breakneck: China's Quest to Engineer the Future. Our discussion tries to tie some of the book's themes to AI (to align with the book...
- [Some thoughts after using AI to help with taxes](https://idratherbewriting.com/blog/taxes-thoughts-using-ai) (2026-04-20): After receiving a letter from the IRS stating that I owed more taxes on a previous year, I used AI to identify the issue -- a missing cost basis on stock sales. I then successfully disputed the not...
- [Podcast: How valuable are agent skills? Conversation with Larah Vasquez and Fabrizio Ferri-Benedetti](https://idratherbewriting.com/blog/ai-skills-agentic-workflows-larah-fabrizio) (2026-04-12): In this podcast, I chat with Larah Vasquez and Fabrizio Ferri-Benedetti about using skills to extend AI capabilities, the future of agentic engineering, local models like Qwen and Gemma, and whethe...
- [The Emerging Picture of a Changed Profession: Cyborg Technical Writers — Augmented, Not Replaced, by AI](https://idratherbewriting.com/blog/cyborg-model-emerging-talk) (2026-04-05): I recently gave a presentation to students and faculty in person at Louisiana Tech University on March 30, 2026, focusing on what I call the cyborg model of technical writing. The idea is that the ...
- [Will tech writers survive AI? Perspectives from two professors, Nupoor Ranade and Jeremy Merritt](https://idratherbewriting.com/blog/will-tech-writers-survive-ai-academics-nupoor-jeremy) (2026-03-21): In this podcast, I chat with two professors — Nupoor Ranade (Carnegie Mellon) and Jeremy Merritt (James Madison University) — about how AI is reshaping the technical writing profession from the aca...
- [AI Book Club recording of 'If Anyone Builds It, Everyone Dies'](https://idratherbewriting.com/blog/ai-book-club-if-anyone-builds-it) (2026-03-17): This is a recording of our AI Book Club discussion of If Anyone Builds It, Everyone Dies: Why Superhuman AI Will Kill Us All by Nate Soares and Eliezer Yudkowsky, held March 15, 2026. Our discussio...
- [Recording of Automation Engineering 101 for Tech Docs presentation at WTD West Coast Supermeetup](https://idratherbewriting.com/blog/auto-engineering-101-presentation-wtd) (2026-03-12): I recently gave a presentation titled Automation Engineering 101 for Tech Docs at the Write the Docs West Coast Supermeetup. I was one of two presenters. The talk covers seven principles for design...
- [Cracking the code on corporate visibility](https://idratherbewriting.com/blog/cracking-the-code-on-corp-visibility) (2026-03-08): If you create content and share it with people around you, whether it's blog posts and podcasts on the web, or educational offerings internally at your company, you become much more visible to thos...
- [Podcast: Doc testing, skills files, and the guardians of knowledge -- with Manny Silva](https://idratherbewriting.com/blog/podcast-silva-guardians-of-knowledge) (2026-03-08): In this podcast, Fabrizio Ferri-Benedetti (passo.uno) and I chat with Manny Silva (instructionmanuel.com), head of documentation at Skyflow and author of Docs as Tests. Manny is working on a follow...
- [Nobody knows what it will look like in 2 years](https://idratherbewriting.com/blog/nobody-knows-two-years-from-now) (2026-03-03): Nobody knows what programming will look like in two years by Charles Humble (published Feb 18, 2026, on LeadDev.com) is an honest, refreshing take from a programmer wrestling with the uncertainty o...
- [Good shot, GUS!!!! How to win at pickup basketball even if you're not all that great](https://idratherbewriting.com/blog/win-at-pickup-basketball-praising-comments) (2026-03-01): Combining praise with names can have a powerful effect on performance. On the pickup basketball court, the effect can be transformative, making everyone play their best. But it also creates a trans...
- [10 principles of the cyborg technical writer -- brief notes and bullet points on how to use AI to augment your role](https://idratherbewriting.com/blog/10-principles-of-cyborg-technical-writer) (2026-02-27): In my post The Emerging Picture of a Changed Profession: Cyborg Technical Writers — Augmented, Not Replaced, by AI, I mentioned an upcoming presentation I'm giving to students and faculty. I argue ...
- [World Brain: No Experts podcast - Three tech writers and a photographer walk into a bar (with Tom Johnson and Floyd Jones)](https://idratherbewriting.com/blog/world-brain-no-experts-podcast-guest) (2026-02-25): I recently appeared as a guest on the World Brain: No Experts podcast, episode 5, titled 'Three tech writers and a photographer walk into a bar (with Tom Johnson and Floyd Jones).' We chat about a ...
- [Using curiosity to decenter](https://idratherbewriting.com/blog/using-curiosity-to-decenter) (2026-02-16): Although I don't write much about psychology, I've recently become fascinated by a technique I learned, similar to cognitive decentering but with a slight variation. The technique works quite well,...

## About and contact

- [About me](https://idratherbewriting.com/aboutme/): Bio and background
- [Contact](https://idratherbewriting.com/contact/): How to reach Tom
- [Newsletter](https://idratherbewriting.com/newsletter/): Email newsletter signup
- [Presentations](https://idratherbewriting.com/presentations/): Talks and workshop recordings
- [Podcast](https://idratherbewriting.com/podcasts/): Podcast episodes and interviews
- [Advertising](https://idratherbewriting.com/advertising/): Sponsorship information
- [Copyright and reuse](https://idratherbewriting.com/copyright/): Licensing terms for this content

## Optional

Bulk indexes and archives. Skip these if you need a shorter context.

- [XML sitemap](https://idratherbewriting.com/sitemap.xml): Machine-readable URL list
- [RSS feed](https://idratherbewriting.com/feed.xml): Latest posts
- [Podcast RSS feed](https://idratherbewriting.com/itunes.rss): Podcast episodes
- [All posts by year](https://idratherbewriting.com/all/): Every post, grouped by year
- [Tags](https://idratherbewriting.com/tags/): Posts grouped by tag
- [Journey away from smartphones](https://idratherbewriting.com/smartphones/index.html): Series on reducing smartphone dependence
- [Rereading Zen and the Art of Motorcycle Maintenance](https://idratherbewriting.com/zamm/why-reread-zen-and-art-of-motorcycle-maintenance.html): Chapter-by-chapter reflections

### Blog categories

- [academics-and-practitioners](https://idratherbewriting.com/category-academics-and-practitioners/)
- [ai](https://idratherbewriting.com/category-ai/)
- [api-doc](https://idratherbewriting.com/category-api-doc/)
- [api-doc-site-updates](https://idratherbewriting.com/category-api-doc-site-updates/)
- [beginners](https://idratherbewriting.com/category-beginners/)
- [biking](https://idratherbewriting.com/category-biking/)
- [blogging](https://idratherbewriting.com/category-blogging/)
- [book-reviews](https://idratherbewriting.com/category-book-reviews/)
- [creativity](https://idratherbewriting.com/category-creativity/)
- [dita](https://idratherbewriting.com/category-dita/)
- [family](https://idratherbewriting.com/category-family/)
- [findability](https://idratherbewriting.com/category-findability/)
- [technical-writing](https://idratherbewriting.com/category-technical-writing/)
- [innovation](https://idratherbewriting.com/category-innovation/)
- [jekyll](https://idratherbewriting.com/category-jekyll/)
- [jobs](https://idratherbewriting.com/category-jobs/)
- [news](https://idratherbewriting.com/category-news/)
- [podcasts](https://idratherbewriting.com/category-podcasts/)
- [podcasting](https://idratherbewriting.com/category-podcasting/)
- [podcast-guest](https://idratherbewriting.com/category-podcast-guest/)
- [quick-reference-guides](https://idratherbewriting.com/category-quick-reference-guides/)
- [screencasting](https://idratherbewriting.com/category-screencasting/)
- [simplifying-complexity](https://idratherbewriting.com/category-simplifying-complexity/)
- [user-centered-documentation](https://idratherbewriting.com/category-user-centered-documentation/)
- [video](https://idratherbewriting.com/category-video/)
- [visual-communication](https://idratherbewriting.com/category-visual-communication/)
- [web-design](https://idratherbewriting.com/category-web-design/)
- [wtd-podcasts](https://idratherbewriting.com/category-wtd-podcasts/)
- [wikis](https://idratherbewriting.com/category-wikis/)
- [wordpress](https://idratherbewriting.com/category-wordpress/)
- [writing](https://idratherbewriting.com/category-writing/)

### Documenting APIs course — all topics

- [Overview](https://idratherbewriting.com/learnapidoc/docapis_overview.html)
- [Course introduction](https://idratherbewriting.com/learnapidoc/index.html)
- [Why I developed this course](https://idratherbewriting.com/learnapidoc/docapis_foreword.html)
- [About the author](https://idratherbewriting.com/learnapidoc/docapis_about_the_author.html)
- [Download PDFs](https://idratherbewriting.com/learnapidoc/download.html)
- [Workshop video recordings](https://idratherbewriting.com/learnapidoc/docapis_course_videos.html)
- [Workshop agenda, slides, activities](https://idratherbewriting.com/learnapidoc/workshop.html)
- [What's new](https://idratherbewriting.com/learnapidoc/docapis_whats_new.html)
- [Overview](https://idratherbewriting.com/learnapidoc/docapis_introtoapis.html)
- [Introduction to REST API documentation](https://idratherbewriting.com/learnapidoc/docapis_intro_to_rest_api_doc.html)
- [What is a REST API?](https://idratherbewriting.com/learnapidoc/docapis_what_is_a_rest_api.html)
- [Activity: Identify your goals](https://idratherbewriting.com/learnapidoc/docapis_identify_your_goals.html)
- [Developer Documentation Trends: Survey Results](https://idratherbewriting.com/learnapidoc/docapis_trends.html)
- [Overview](https://idratherbewriting.com/learnapidoc/likeadeveloper.html)
- [Scenario for using a weather API](https://idratherbewriting.com/learnapidoc/docapis_scenario_for_using_weather_api.html)
- [Get authorization keys](https://idratherbewriting.com/learnapidoc/docapis_get_auth_keys.html)
- [Submit requests through Postman](https://idratherbewriting.com/learnapidoc/docapis_postman.html)
- [curl intro and installation](https://idratherbewriting.com/learnapidoc/docapis_install_curl.html)
- [Make a curl call](https://idratherbewriting.com/learnapidoc/docapis_make_curl_call.html)
- [Understand curl more](https://idratherbewriting.com/learnapidoc/docapis_understand_curl.html)
- [Activity: Use methods with curl](https://idratherbewriting.com/learnapidoc/docapis_curl_with_petstore.html)
- [Analyze the JSON response](https://idratherbewriting.com/learnapidoc/docapis_analyze_json.html)
- [Inspect the JSON from the response payload](https://idratherbewriting.com/learnapidoc/docapis_json_console.html)
- [Access and print a specific JSON value](https://idratherbewriting.com/learnapidoc/docapis_access_json_values.html)
- [Dive into dot notation](https://idratherbewriting.com/learnapidoc/docapis_diving_into_dot_notation.html)
- [Overview](https://idratherbewriting.com/learnapidoc/docendpoints.html)
- [A new endpoint to document](https://idratherbewriting.com/learnapidoc/docapis_new_endpoint_to_doc.html)
- [API reference tutorial overview](https://idratherbewriting.com/learnapidoc/docapis_api_reference_tutorial_overview.html)
- [Step 1: Resource description](https://idratherbewriting.com/learnapidoc/docapis_resource_descriptions.html)
- [Step 2: Endpoints and methods](https://idratherbewriting.com/learnapidoc/docapis_resource_endpoints.html)
- [Step 3: Parameters](https://idratherbewriting.com/learnapidoc/docapis_doc_parameters.html)
- [Step 4: Request example](https://idratherbewriting.com/learnapidoc/docapis_doc_sample_requests.html)
- [Step 5: Response example and schema](https://idratherbewriting.com/learnapidoc/docapis_doc_sample_responses_and_schema.html)
- [Putting it all together](https://idratherbewriting.com/learnapidoc/docapis_finished_doc_result.html)
- [Activity: What's wrong with this API reference topic](https://idratherbewriting.com/learnapidoc/docapis_api_whats_wrong_activity.html)
- [Activity: Evaluate API reference docs for core elements](https://idratherbewriting.com/learnapidoc/docapis_api_reference_activity.html)
- [Overview](https://idratherbewriting.com/learnapidoc/restapispecifications.html)
- [Overview of REST API specification formats](https://idratherbewriting.com/learnapidoc/pubapis_rest_specification_formats.html)
- [Introduction to the OpenAPI specification](https://idratherbewriting.com/learnapidoc/pubapis_openapi_intro.html)
- [Stoplight: Visual modeling tools for creating your spec](https://idratherbewriting.com/learnapidoc/pubapis_stoplight.html)
- [Getting started tutorial: Using Stoplight to create an OpenAPI specification document](https://idratherbewriting.com/learnapidoc/pubapis_openapis_quickstart_stoplight.html)
- [Swagger UI tutorial](https://idratherbewriting.com/learnapidoc/pubapis_swagger.html)
- [SwaggerHub introduction and tutorial](https://idratherbewriting.com/learnapidoc/pubapis_swaggerhub_smartbear.html)
- [Swagger UI Demo](https://idratherbewriting.com/learnapidoc/pubapis_swagger_demo.html)
- [Integrating Swagger UI with the rest of your docs](https://idratherbewriting.com/learnapidoc/pubapis_combine_swagger_and_guide.html)
- [Redocly tutorial -- authoring and publishing API docs with Redocly's command-line tools](https://idratherbewriting.com/learnapidoc/pubapis_redocly.html)
- [Redoc Community Edition Basic Demo](https://idratherbewriting.com/learnapidoc/pubapis_redoc.html)
- [Document360 for API docs](https://idratherbewriting.com/learnapidoc/pubapis_document360.html)
- [Overview](https://idratherbewriting.com/learnapidoc/openapi_tutorial.html)
- [OpenAPI tutorial using Swagger Editor and Swagger UI: Overview](https://idratherbewriting.com/learnapidoc/pubapis_openapi_tutorial_overview.html)
- [Working in YAML](https://idratherbewriting.com/learnapidoc/pubapis_yaml.html)
- [Step 1: The openapi object](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step1_openapi_object.html)
- [Step 2: The info object](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step2_info_object.html)
- [Step 3: The servers object](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step3_servers_object.html)
- [Step 4: The paths object](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step4_paths_object.html)
- [Step 5: The components object](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step5_components_object.html)
- [Step 6: security object](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step6_security_object.html)
- [Step 7: The tags object](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step7_tags_object.html)
- [Step 8: The externalDocs object](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step8_externaldocs_object.html)
- [Step 9: Other elements: webhooks and jsonSchemaDialect](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step9_other_elements.html)
- [Activity: Create an OpenAPI specification document](https://idratherbewriting.com/learnapidoc/pubapis_openapi_activity.html)
- [Overview](https://idratherbewriting.com/learnapidoc/testingdocs.html)
- [Overview of testing your docs](https://idratherbewriting.com/learnapidoc/testingdocs_overview.html)
- [Set up a test environment](https://idratherbewriting.com/learnapidoc/testingdocs_test_environment.html)
- [Test all instructions yourself](https://idratherbewriting.com/learnapidoc/testingdocs_test_your_instructions.html)
- [Test your assumptions](https://idratherbewriting.com/learnapidoc/testingdocs_testing_assumptions.html)
- [Activity: Test your project's documentation](https://idratherbewriting.com/learnapidoc/testingdocs_activity.html)
- [Overview](https://idratherbewriting.com/learnapidoc/docconceptual.html)
- [API conceptual topics overview](https://idratherbewriting.com/learnapidoc/docapis_conceptual_topics_overview.html)
- [API product overviews](https://idratherbewriting.com/learnapidoc/docapis_doc_overview.html)
- [API getting started tutorials](https://idratherbewriting.com/learnapidoc/docapis_doc_getting_started_section.html)
- [API authentication and authorization](https://idratherbewriting.com/learnapidoc/docapis_more_about_authorization.html)
- [API status and error codes](https://idratherbewriting.com/learnapidoc/docapis_doc_status_codes.html)
- [API rate limiting and thresholds](https://idratherbewriting.com/learnapidoc/docapis_rate_limiting_and_thresholds.html)
- [API quick reference](https://idratherbewriting.com/learnapidoc/docapis_doc_quick_reference.html)
- [API glossary](https://idratherbewriting.com/learnapidoc/docapis_glossary_section.html)
- [API best practices](https://idratherbewriting.com/learnapidoc/docapis_best_practices_with_api.html)
- [Activity: Complete the SendGrid Getting Started tutorial](https://idratherbewriting.com/learnapidoc/docapis_getting_started_activity.html)
- [Activity: Assess the conceptual content in your project](https://idratherbewriting.com/learnapidoc/docapis_concept_activity.html)
- [Overview](https://idratherbewriting.com/learnapidoc/docapiscode.html)
- [Common characteristics of code tutorials](https://idratherbewriting.com/learnapidoc/docapis_code_tutorials_common_characteristics.html)
- [Why documenting code is so difficult](https://idratherbewriting.com/learnapidoc/docapis_code_difficulty.html)
- [What research tells us about documenting code](https://idratherbewriting.com/learnapidoc/docapiscode_research_on_documenting_code.html)
- [Five strategies for documenting code](https://idratherbewriting.com/learnapidoc/docapis_code_strategies.html)
- [Code samples](https://idratherbewriting.com/learnapidoc/docapis_codesamples_bestpractices.html)
- [Sample apps](https://idratherbewriting.com/learnapidoc/docapis_sample_apps.html)
- [SDKs (software development kits)](https://idratherbewriting.com/learnapidoc/docapis_sdks.html)
- [API design and usability](https://idratherbewriting.com/learnapidoc/evaluating-api-design.html)
- [Developer experience (DevX) usability](https://idratherbewriting.com/learnapidoc/devx-usability-examples.html)
- [Overview](https://idratherbewriting.com/learnapidoc/writing_process.html)
- [Overview of the writing process](https://idratherbewriting.com/learnapidoc/docapis_writing_process_overview.html)
- [1. Planning](https://idratherbewriting.com/learnapidoc/docapis_planning.html)
- [2. Information gathering](https://idratherbewriting.com/learnapidoc/docapis_information_gathering.html)
- [3. Writing](https://idratherbewriting.com/learnapidoc/docapis_writing.html)
- [4. Reviewing](https://idratherbewriting.com/learnapidoc/docapis_reviewing.html)
- [5. Publishing](https://idratherbewriting.com/learnapidoc/docapis_publishing.html)
- [Overview](https://idratherbewriting.com/learnapidoc/publishingapis.html)
- [Overview for publishing API docs](https://idratherbewriting.com/learnapidoc/pubapis_overview.html)
- [Survey of API doc sites](https://idratherbewriting.com/learnapidoc/pubapis_apilist.html)
- [Design patterns with API doc sites](https://idratherbewriting.com/learnapidoc/pubapis_design_patterns.html)
- [Docs-as-code tools](https://idratherbewriting.com/learnapidoc/pubapis_docs_as_code.html)
- [More about Markdown](https://idratherbewriting.com/learnapidoc/pubapis_markdown.html)
- [Version control systems](https://idratherbewriting.com/learnapidoc/pubapis_version_control.html)
- [Static site generators](https://idratherbewriting.com/learnapidoc/pubapis_static_site_generators.html)
- [Hosting and deployment options](https://idratherbewriting.com/learnapidoc/pubapis_hosting_and_deployment.html)
- [Hybrid documentation systems](https://idratherbewriting.com/learnapidoc/pubapis_hybrid_systems.html)
- [Which tool to choose for API docs — my recommendations](https://idratherbewriting.com/learnapidoc/pubapis_which_tool_to_choose.html)
- [Overview](https://idratherbewriting.com/learnapidoc/publishingtools.html)
- [Activity: Manage content in a GitHub wiki](https://idratherbewriting.com/learnapidoc/pubapis_github_wikis.html)
- [Activity: Use the GitHub Desktop Client](https://idratherbewriting.com/learnapidoc/pubapis_github_desktop_client.html)
- [Activity: Pull request workflows through GitHub](https://idratherbewriting.com/learnapidoc/pubapis_github_pull_requests.html)
- [Jekyll and CloudCannon continuous deployment tutorial](https://idratherbewriting.com/learnapidoc/pubapis_jekyll.html)
- [Using Oxygen XML with docs-as-code workflows](https://idratherbewriting.com/learnapidoc/pubapis_oxygenxml.html)
- [Case study: Switching tools to docs-as-code](https://idratherbewriting.com/learnapidoc/pubapis_switching_to_docs_as_code.html)
- [Tools FAQ](https://idratherbewriting.com/learnapidoc/docapis_faq_tools.html)
- [Overview](https://idratherbewriting.com/learnapidoc/jobapis.html)
- [The job market for API technical writers](https://idratherbewriting.com/learnapidoc/jobapis_overview.html)
- [How much code do you need to know?](https://idratherbewriting.com/learnapidoc/jobapis_learning_code.html)
- [Best locations for API documentation jobs](https://idratherbewriting.com/learnapidoc/jobapis_location.html)
- [Activity: Find an Open-Source Project](https://idratherbewriting.com/learnapidoc/docapis_find_open_source_project.html)
- [Activity: Create or fix an API reference documentation topic](https://idratherbewriting.com/learnapidoc/docapis_work_on_conceptual_topic.html)
- [Overview](https://idratherbewriting.com/learnapidoc/nativelibraryapis.html)
- [Overview of native library APIs](https://idratherbewriting.com/learnapidoc/nativelibraryapis_overview.html)
- [Get the sample Java project](https://idratherbewriting.com/learnapidoc/nativelibraryapis_getting_the_source.html)
- [Java crash course](https://idratherbewriting.com/learnapidoc/nativelibraryapis_java_crash_course.html)
- [Activity: Generate a Javadoc from a sample project](https://idratherbewriting.com/learnapidoc/nativelibraryapis_create_javadoc.html)
- [Javadoc tags](https://idratherbewriting.com/learnapidoc/nativelibraryapis_javadoc_tags.html)
- [Explore the Javadoc output](https://idratherbewriting.com/learnapidoc/nativelibraryapis_exploring_javadoc_output.html)
- [Make edits to Javadoc tags](https://idratherbewriting.com/learnapidoc/nativelibraryapis_editing_javadoc.html)
- [Doxygen, a document generator mainly for C++](https://idratherbewriting.com/learnapidoc/nativelibraryapis_doxygen.html)
- [Create non-ref docs with native library APIs](https://idratherbewriting.com/learnapidoc/nativelibraryapis_nonrefdocs.html)
- [Overview](https://idratherbewriting.com/learnapidoc/docapis_managing_doc_processes.html)
- [DX content strategy with developer portals](https://idratherbewriting.com/learnapidoc/docapis_dx_content_strategy.html)
- [Following agile scrum with documentation projects](https://idratherbewriting.com/learnapidoc/pubapis_agile_scrum_for_docs.html)
- [Managing large documentation projects](https://idratherbewriting.com/learnapidoc/docapis_managing_doc_projects.html)
- [Managing small documentation requests](https://idratherbewriting.com/learnapidoc/docapis_managing_small_doc_requests.html)
- [Managing SDK releases](https://idratherbewriting.com/learnapidoc/docapis_managing_sdk_releases.html)
- [Documentation kickoff meetings and product demos](https://idratherbewriting.com/learnapidoc/docapis_kickoff_meeting_agenda.html)
- [Processes for reviewing documentation](https://idratherbewriting.com/learnapidoc/docapis_review_processes.html)
- [Maintaining existing documentation](https://idratherbewriting.com/learnapidoc/docapis_doc_maintenance_processes.html)
- [Collecting feedback post-release](https://idratherbewriting.com/learnapidoc/docapis_collecting_feedback_post_release.html)
- [Managing content from external contributors](https://idratherbewriting.com/learnapidoc/docapis_processes_for_external_contributors.html)
- [Changing internal doc culture](https://idratherbewriting.com/learnapidoc/docapis_changing_internal_doc_culture.html)
- [Sending doc status reports -- a tool for visibility and relationship building](https://idratherbewriting.com/learnapidoc/docapis_status_reports.html)
- [Broadcasting your meeting notes to influence a wider audience](https://idratherbewriting.com/learnapidoc/docapis_meeting_notes.html)
- [Ensuring documentation coverage with each software release](https://idratherbewriting.com/learnapidoc/docapis_release_process.html)
- [Overview](https://idratherbewriting.com/learnapidoc/docapis_metrics_and_measurement.html)
- [Measuring documentation quality through user feedback](https://idratherbewriting.com/learnapidoc/docapis_measuring_impact.html)
- [Different approaches for assessing information quality](https://idratherbewriting.com/learnapidoc/docapis_metrics_assessing_information_quality.html)
- [Quality checklist for API documentation](https://idratherbewriting.com/learnapidoc/docapis_quality_checklist.html)
- [Quantifying your progress](https://idratherbewriting.com/learnapidoc/docapis_metrics_quantifying_progress.html)
- [Overview](https://idratherbewriting.com/learnapidoc/glossary_overview.html)
- [Glossary](https://idratherbewriting.com/learnapidoc/glossary.html)
- [Glossary groups](https://idratherbewriting.com/learnapidoc/glossary_groups.html)
- [Overview](https://idratherbewriting.com/learnapidoc/resources.html)
- [Documenting GraphQL APIs](https://idratherbewriting.com/learnapidoc/docapis_graphql_apis.html)
- [More REST API activities](https://idratherbewriting.com/learnapidoc/docapis_more_rest_activities.html)
- [Activity: Get event information using the Eventbrite API](https://idratherbewriting.com/learnapidoc/docapis_eventbrite_example.html)
- [Activity: Retrieve a gallery using the Flickr API](https://idratherbewriting.com/learnapidoc/docapis_flickr_example.html)
- [Activity: Get wind speed using the Xweather API](https://idratherbewriting.com/learnapidoc/docapis_xweather_example.html)
- [RAML tutorial](https://idratherbewriting.com/learnapidoc/pubapis_raml.html)
- [API Blueprint tutorial](https://idratherbewriting.com/learnapidoc/pubapis_api_blueprint.html)
- [API jeopardy answer key](https://idratherbewriting.com/learnapidoc/jeopardy_answer_key.html)
- [What's wrong with this topic answer key](https://idratherbewriting.com/learnapidoc/whats_wrong_answer_key.html)
- [Menlo Park API workshop video recording](https://idratherbewriting.com/learnapidoc/menlo_park_workshop_recording.html)
- [Denver API workshop video recording](https://idratherbewriting.com/learnapidoc/denver_workshop_recording.html)
- [API doc presentation video recordings](https://idratherbewriting.com/learnapidoc/api_doc_presentations.html)