The following are summaries of interesting articles from around the web, as well as my commentary. Daniel Beck debunks myths surrounding open-source documentation portfolios. Silicon Valley's top AI firms are intriguingly recruiting poets. Jason Bailey supports Emma Thompson's stance on the term 'content' being disrespectful. The potential of A.I. is examined beyond the hype, emphasizing its aid for human writers and editors. Ivan Walsh provides insights on optimizing ChatGPT prompts for technical summaries, while Ellis Pratt discusses how AI agents can be a time-saver for technical writers.
If AI transforms the tech writing field, as many think it will, we'll face a choice of either resisting change and skirting with obsolescence, or reinventing our professional identity. Reinventing one's identity, particularly letting go of the sense of being a writer first and foremost, is psychologically difficult. We need to dedicate time to redefining our role through high-risk, high-reward experiments. But what the experiments should be, exactly, remains unclear.
The following are summaries of interesting articles from around the web, as well as my commentary. Seth Godin shares his insights on the failure of manuals. The MDN team offers a postmortem reflection on 'AI Explain.' Zohra Mutabanna's podcast features Caity Cronkhite discussing the AI-driven future of technical writing. Fabrizio Ferri Benedetti draws intriguing parallels between documentation types and animals in 'Bestiary.'
I added a new article in my API course called '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 article focuses on clarifying those scenarios where AI excels and where it doesn't, particularly for technical writers creating documentation. I also argue for the inevitability of AI integration through an argument referred to as the 'obsolescence regime.'
In this post, I compare ChatGPT and Claude on an Alaskan cruise. Claude seems better at handling long content, and ChatGPT shorter content. Using both chatbots, I asked many questions to learn about my cruise surroundings. The chatbots expanded my curiosity and made me more attentive to my environment by encouraging endless questions.
A few weeks ago I mentioned Alphadoc, a new tool for publishing API documentation. The following is a Q&A with Daan Stolk, cofounder/CPO of Alphadoc. In the following questions, Daan tells the story behind Alphadoc and what makes it unique from other API documentation tools.
Providing summaries of content is one of the most useful and powerful capabilities of AI chatbots powered by large language models (LLMs), like ChatGPT, Bard, and Claude. As such, AI chatbots can significantly help tech writers in a variety of documentation-related tasks, such as generating summaries at the top of each document, generating product overviews that summarize features and capabilities, and helping tech writers process content more quickly from long articles, bugs, meetings, and other documents.
Here are a few links from around the web worth reading for September 5, 2023.
Compiling and maintaining glossaries can be time consuming. Can AI tools help with glossaries? Just as AIs are good at creating summaries, providing definitions might be one of AI's strengths. A definition is just a short summary of a concept. AI tools are also good at identifying potentially unfamiliar, jargon-filled terms and then listing concise definitions for them.
The best scenarios to implement AI are those tasks that humans perform poorly but robots perform excellently. One of these task domains is comparative analysis, specifically comparing two sets of information to identify inconsistencies. API responses can be complex, with a wide variety of fields that can be returned depending on the request. As humans, it can be hard to compare large amounts of text quickly, but AI tools might be good at this task.
One of the main ways I use AI is with thematic analysis, which involves identifying, analyzing, and reporting patterns (themes) within qualitative data. After you identify major themes, you can use least-to-most prompting techniques to go into more detail. I recently used this technique in preparing notes for a book club. It could also could work well for a number of documentation-related scenarios. In this article, I explore using AI for thematic analysis with doc feedback, search analytics, tags and related pages, FAQs, glossary items, bugs, and documentation pages.
I added a new article to my API doc course on using AI for language advice. When you have questions about style, grammar, or other syntax, try asking your favorite AI tool. AI tools can do an excellent job at identifying the particular grammar or style rule or reason, and they can provide guidance about why one phrasing is preferable to another. In asserting a preference, AI will often make a convincing argument for one style over another, such as noting that a word could be interpreted in different ways and so is more ambiguous than the other phrasing.
I added a new article to my API course about using AI to create doc updates based on bugs. By bugs, I'm referring to small issues often surfaced by users about the docs. Bugs are often long lists of random fixes to make with the docs, often involving a small number of changed lines. However, interpreting the bugs can be challenging. Fortunately, AI tools can help you understand the issue and resolution.
I added a new AI topic to my API doc course: Using AI to learn coding. One challenge API technical writers face is understanding developer code and tools. This is by far the most intimidating aspect of being an API technical writer. As if documenting code for one project weren't enough, API technical writers must also support multiple projects simultaneously, often with different types of code. You might document a Java API for one project, a REST API for another project, some Go code for an SDK, some C++ code for another project, and so on. It can be nearly impossible to be fluent in all of these languages. Fortunately, you can use AI tools to learn code more efficiently. AI tools can act like a friendly programming buddy who is sitting next to you, ready to explain anything you want, at whatever technical level you need. You can zero in on a specific question or broaden it out to increase your understanding from ground zero.
I added a new article to my API doc course about using AI tools to write scripts. At the core of API documentation work is building, staging, and publishing of API reference content. Whether it’s Javadoc, Doxygen, OpenAPI, or other reference output, almost every API has reference documentation that you build, stage, and publish with each release. Given the centrality of documentation building and publishing tasks, AI tools can be a great help when it comes to configuring scripts to perform these tasks. This is one AI area few people are focusing on, but scripts are an easy way to incorporate AI to improve your productivity and reduce the tediousness of document production.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.