--- title: "AI and APIs: What works, what doesn’t" date: 2026-09-28 description: "In conversations about AI, a lot of people ask the same questions: What kind of scenarios is AI good for? What works, what doesn’t? In which scenarios? This section focuses..." canonical_url: https://idratherbewriting.com/ai/docapis_ai_what_works_and_doesnt --- # AI and APIs: What works, what doesn’t In conversations about AI, a lot of people ask the same questions: What kind of scenarios is AI good for? What works, what doesn’t? In which scenarios? This section focuses on clarifying those scenarios where AI excels, particularly for technical writers creating documentation. I also argue for the inevitability of AI integration through an argument referred to as the “obsolescence regime.” - [Discussion](#discussion) - [Alternative ending to Sarah’s obsolescence](#alternative-ending-to-sarahs-obsolescence) Here’s a video on this topic: ## Moving past the AI hype cycle The topic of AI evokes strong reactions from tech writers: - Some people are apathetic, not even trying the tools. They feel the AI craze will pass, just like other fads (crowdsourcing, wikis, the semantic web, etc.). - Some have drunk the AI Kool-aid and integrated AI into every application and workflow they can imagine. They’ve largely replaced their search engine with AI and subscribed to a dozen AI-focused newsletters to drink the firehose of never-ending AI information. - Some fit somewhere in the middle: skeptical about some AI uses, intrigued by others. They know AI tools will play an important role in shaping the tech writing profession, but they aren’t sure how to apply them. In the context of tech comm, AI seems to be good for something, but what? I drank the AI Kool-aid early on when I realized (after using AI chats for coding tutorials) that [AI chat interfaces could become the primary user interface to read documentation](https://idratherbewriting.com/blog/ai-chat-interfaces-are-the-new-user-interface-for-docs). So I’m the second bullet there. But as I’ve tried to use AI tools to write blog posts, brainstorm, upgrade my site’s code, analyze information, and more, I’ve found AI’s uses more limited than I initially thought. For me, my journey on the AI hype cycle looks like this: ![The hype cycle with AI](https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/api/hypecycle2.jpg) My general strategy for using AI is as follows: In which tasks do AI tools excel, but which humans perform poorly? Those are the tasks to use AI. To determine what works and doesn’t, I try AI tools out in real tech comm scenarios. Nothing moves you past the hype cycle’s peak more than actually trying AI out in documentation-related tasks. Although full access to tool usage for corporate documentation is still heavily restricted, I’ve often resorted to using the tools on my API course content, blog, and elsewhere. I’ve found the following 9 scenarios to work well. ## 9 tech comm use cases for AI The following are 9 scenarios where AI works well: - [Develop build and publishing scripts](ai-tools-build-publish-api-docs.html) - [Understand the meaning of code](docapis_ai_learn_coding.html) - [Distill needed updates from bug threads](docapis_ai_fix_bugs.html) - [Create summaries](docapis_ai_summaries.html) - [Synthesize insights from granular data](docapis_thematic_analysis.html) - [Seek advice on grammar and style](docapis_ai_language_advice.html) - [Arrange content into information type patterns](docapis_pattern_prompts.html) - [Compare API responses to identify discrepancies](docapis_ai_comparison_tasks.html) - [Draft glossary definitions](docapis_ai_glossary_definitions.html) I’ve tried to make these use cases specific and concrete. If I could extrapolate larger patterns, I’d say AI tools excel at these kinds of problems: - Pattern-matching - Classification - Summarization/distillation - Definition - Comparison - Providing examples - Simplification - Formatting - General coding - General explanations ## 10 scenarios where AI tools don’t help much On the flip side, there are also scenarios where AI seems to be a poor fit. Here are 10 examples: - Write specialized or creative content (not found on the web) - Explain specialized knowledge (not found on the web) - Gather stakeholder reviews on docs - Plan and prioritize documentation work - Structure dev portal information flows - Interview subject matter experts - Clarify ambiguity about doc requests - Attend doc sync meetings with teams - Test the accuracy of instructions - Assess the rationale behind doc changes Interestingly, people tend to be more intrigued by the scenarios where AI tools fail than succeed. Perhaps we’re tired of the oversold narrative that AI is going to automate away every aspect of our jobs. Why doesn’t AI work in these scenarios? Information might be implicit/contextual rather than explicit. For example, in goal planning, unless all the information is stated about the tasks’ priority, severity, goal relatedness, product relationships, urgency, etc., it’s difficult for an AI tool to provide good recommendations. In fact, even without AI to help, goal planning requires a tremendous effort to gather information from many different sources. Few of us even have all this information at hand when we plan manually. Other tasks might not involve prediction or pattern matching. For example, interviewing subject matter experts would be hard to automate through AI. Conversations tend to follow less predictable patterns. Each unique answer prompts the next unique question, and so on. Conversations have a dynamic, semi-random shape. It’s also easy to overestimate AI tools’ computational abilities, forgetting that they’re just prediction machines—able to complete the blanks in a sentence based on extensive pattern matching. LLMs are good at pattern recognition and predicting text, but lack general intelligence. They cannot do true mathematical reasoning or complex logical inference beyond their training data. Finally, to expand on the last point, going beyond training data is usually a need with tech docs. Most technical writers work on documentation for products and features not yet released, or if released, the docs exist behind firewalls and aren’t on the web. For general, Wikipedia-like information that’s part of the LLM’s training data, AI responses are pretty good. But for information outside the web or offline, AI tools make guesses based on word associations that are often wrong. Although outside the scope of tech writers’ work, when it comes to creative content, AI tools also produce below-average content. In my experience, an AI can usually fix a problematic sentence or paragraph, rewriting it with more clarity, or maybe offer an explanation that provides more clarity. However, when you let its writing capabilities loose on a full-length article where personality, voice, and experience are interwoven as a personal essay, the result is subpar. That said, with the right prompting techniques, you can get decent results in places for specific needs. I’ve used Claude.ai to assist with some of the content in this article. ## Caveats and constant tool evolution It could be that I just haven’t landed on the right approach to use AI in many scenarios. Or maybe better techniques will eventually surface in the rapidly evolving AI tools and apps. AI tools are rapidly changing and evolving. What may be true today might not apply tomorrow. Despite generative AI tools going mainstream many months ago, most companies still prohibit tech writers from using AI with confidential data, fearing that the confidential information will end up as LLM training data. After generative AI tools become common in the workplace, the applicable use cases for AI will probably grow significantly. I suspect tech writers will eventually be asked to implement AI tools more commonly in their workplace environments. (Nothing will enforce that integration more than reductions in tech writer staffing.) At any rate, looking at these 10 scenarios where AI isn’t useful provides some reassurance as a technical writer. If AI can’t perform those tasks, which make up a large chunk of what I do all day, there’s a low chance that AI will entirely replace technical writer roles.