I'd Rather Be Writing, by Tom Johnson Technical writing blog focusing on the latest trends, news, and other topics in the field of technical communication. https://idratherbewriting.com/ Wed, 29 Nov 2023 13:59:22 -0800 Wed, 29 Nov 2023 13:59:22 -0800 Jekyll v3.9.3 Why I decided to reread Zen and the Art of Motorcycle Maintenance (ZAMM series) I recently decided to reread a classic in the tech comm field: Robert Pirsig's <i>Zen and the Art of Motorcycle Maintenance</i>, nearly 50 years after it was first published. I wondered if Pirsig had more insights about technical writing than I initially understood when I first read the book long ago. In this introduction to an upcoming series, I list a few parallels and questions I'm hoping to answer. Sun, 26 Nov 2023 00:00:00 -0800 https://idratherbewriting.com/zamm/zamm-why-reread-zen-and-art-of-motorcycle-maintenance.html https://idratherbewriting.com/zamm/zamm-why-reread-zen-and-art-of-motorcycle-maintenance.html technical-writing Podcast: Tech writing and Zen and the Art of Motorcycle Maintenance, with Dan Grabski (ZAMM series) In this episode, I chat with Dan Grabski, a senior content developer based in Portland, both about his recent WTD talk titled 'Zen and the Art of Manually Creating API Documentation' and Robert Pirsig's 'Zen and the Art of Motorcycle Maintenance.' Dan explains the importance of focusing not just on technical details of implementations but also on integrating the people side &mdash; on understanding the perspectives of different users and stakeholders involved. Dan provides examples from his engineering background to illustrate how intuition develops from experience, how to avoid spectator mode through hands-on exploration of APIs, on carving out time to devote to continual learning, and the value of incremental progress. Overall, it's a great conversation about engaging more deeply with technology to write better documentation. Sat, 18 Nov 2023 00:00:00 -0800 https://idratherbewriting.com/blog/zen-motorcycle-maintenance-dan-grabski https://idratherbewriting.com/blog/zen-motorcycle-maintenance-dan-grabski writing podcasts api-doc Upcoming webinar: Experiments and use cases for AI from a tech writer’s perspective I'm giving a webinar titled 'Experiments and use cases for AI from a tech writer’s perspective' on December 8, 2023. The webinar is sponsored by the STC Washington, DC - Baltimore Chapter. In this presentation, I’ll share some personal experiences in using AI for different writing-related use cases, explaining what I’ve found helpful. These use cases and takeaways are all experiential, based on my experiments with using AI both in the workplace for documentation-related scenarios and writing on my blog. Sat, 18 Nov 2023 00:00:00 -0800 https://idratherbewriting.com/blog/stc-webinar-experiments-use-cases-ai https://idratherbewriting.com/blog/stc-webinar-experiments-use-cases-ai ai You've heard of 'Docs as code' -- Now get ready for 'Code as docs': Q&A with Speakeasy Speakeasy is a platform aimed at simplifying the creation and consumption of APIs. Its primary product is the creation of SDKs (client libraries), but its new offering (and most relevant to technical writers) is the 'Code as Docs' product. Their Code as Docs product embeds SDKs into the traditional API reference, providing users with code snippets in 8+ languages and bridging the gap between documentation and real-world applications. This post is a Q&A with Sagar Batchu, CEO and co-founder of <a href='https://www.speakeasyapi.dev'>Speakeasy</a>. Thu, 09 Nov 2023 00:00:00 -0800 https://idratherbewriting.com/blog/speakeasy-question-answer-code-as-docs https://idratherbewriting.com/blog/speakeasy-question-answer-code-as-docs ai api-doc Doing research with AI tools -- avoiding the trap of fabricated URLs In this short podcast, I explore using AI tools to do research, the potential for fake URLs, and how to deal with the fabrication. I started by using Claude to summarize a podcast and provide a list of salient points, including the potential counterargument. What I didn't expect was for Claude to fabricate a list of imagined research and then summarize the fictitious research to conclude that it lended support for the counterargument. I took Claude's list of research and pasted it into ChatGPT with Bing to browse the real-time web to validate the sources. Using Claude and ChatGPT in combination worked pretty well, but overall this is a tale of caution. You have to be suspicious of research provided by AIs and know how to use each tool according to its strengths. Thu, 09 Nov 2023 00:00:00 -0800 https://idratherbewriting.com/blog/research-with-ai-dealing-with-fake-research https://idratherbewriting.com/blog/research-with-ai-dealing-with-fake-research academics-and-practitioners ai podcasts writing Notes for Building the Cycling City: The Dutch Blueprint for Urban Vitality In <a href='https://www.amazon.com/Building-Cycling-City-Blueprint-Vitality/dp/1610918797'><i>Building the Cycling City: The Dutch Blueprint for Urban Vitality</i></a>, Melissa and Chris Bruntlett describe how the Dutch achieved so much cycling success, and how other cities might do the same. The authors bring up a variety of techniques and approaches the Dutch have used, such as seamlessly integrating cycling with public transit, pursuing customized strategies based on each city's unique landscape and culture, taking an iterative approach to infrastructure, using tactical urbanism and prototyping, and more. Mon, 06 Nov 2023 00:00:00 -0800 https://idratherbewriting.com/blog/building-the-cycling-city-dutch-blueprint-notes https://idratherbewriting.com/blog/building-the-cycling-city-dutch-blueprint-notes biking podcasts Movemate standing board review — fixing your back, legs from sedentary decline from a tech job The Movemate board fits into the genre of work-focused standing boards designed to reduce fatigue while standing at a computer. This Movemate review is a bit different from the normal tech comm content on my blog, but I believe it's just as relevant. If you're sitting right now, does your back hurt a bit? Do your legs feel like they've been shut off and are atrophying? Are you tired of sitting all day every day in front of a screen? It doesn't have to be like that. Sun, 29 Oct 2023 00:00:00 -0700 https://idratherbewriting.com/blog/movemate-review-standing-board https://idratherbewriting.com/blog/movemate-review-standing-board technical-writing My experience trying to write original, full-length human-sounding articles using Claude AI You can use AI tools like Claude to help you write full-length content. By going paragraph-by-paragraph, you can direct the AI while seemingly maintaining your own voice and ideas. However, despite my attempts to use AI with writing, I've found that it's harder to pull off than I thought. I can get close, but due to the way AI tools are trained, they inevitably steer into explanation more than argument. This can remove much of the interest from a personal essay. Wed, 25 Oct 2023 00:00:00 -0700 https://idratherbewriting.com/blog/writing-full-length-articles-with-claude-ai https://idratherbewriting.com/blog/writing-full-length-articles-with-claude-ai ai podcasts writing Chatting about AI trends and tech comm with Fabrizio Ferri Benedetti In this podcast, I chat with Fabrizio Ferri Benedetti, a tech writer in Barcelona who blogs at passo.uno and works for Splunk, about various AI news topics. We talk about the Forrester AI jobs impact forecast, the community element in documentation, the way the profession is changing with AI, content design roles with LLMs, how complex processes and interactions can't be automated, whether the word 'content' is problematic, and more. Fri, 20 Oct 2023 00:00:00 -0700 https://idratherbewriting.com/blog/ai-chat-fabrizio-podcast https://idratherbewriting.com/blog/ai-chat-fabrizio-podcast ai podcasts writing What is Diátaxis and should you be using it with your documentation? The Diátaxis approach to documentation organizes technical documentation into four types — tutorials, how-tos, reference, and explanation. In this post, I compare Diátaxis to DITA, Information Mapping, and the Good Docs Project, explaining similarities and differences. I also point out why identifying information patterns can be so worthwhile as a technical writer, and how identifying these patterns not only grounds our practice in the larger practice of rhetoric but also gives us useful patterns to use with AI tools. Wed, 18 Oct 2023 00:00:00 -0700 https://idratherbewriting.com/blog/what-is-diataxis-documentation-framework https://idratherbewriting.com/blog/what-is-diataxis-documentation-framework technical-writing innovation writing [Podcast] AI and APIs: What works, what doesn't In conversations about AI, a lot of tech writers are asking what kind of scenarios is AI good for? What works, what doesn’t? In which scenarios? You may have read my responses to these questions before in previous posts, but this time I recorded a podcast with slides. In the podcast, I try to pull together these ideas into more of a narrative shape and flow. This podcast 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.' Sat, 14 Oct 2023 00:00:00 -0700 https://idratherbewriting.com/blog/ai-apis-what-works-and-doesnt-video-recording-podcast https://idratherbewriting.com/blog/ai-apis-what-works-and-doesnt-video-recording-podcast ai api-doc technical-writing podcasts writing Forrester Report, Coding jobs, Hyper-personalization, RFPs, Call center replacement (Oct 9, 2023) The following are links from around the web for October 10, 2023. Forrester predicts a major AI impact on U.S. jobs in 2023. A CEO faces backlash for replacing and criticizing human staff with ChatGPT. Zeb Larson assures coders that ChatGPT isn't a job threat, while Rex Woodbury explores the rise of hyper-personalization. Finally, sales execs welcome AI's role in their industry. Mon, 09 Oct 2023 00:00:00 -0700 https://idratherbewriting.com/blog/links-from-web-oct-9 https://idratherbewriting.com/blog/links-from-web-oct-9 ai api-doc jobs writing news What I learned in using AI for planning and prioritization: Content strategy might be safe from automation I experimented with using AI tools to help with planning and prioritizing my documentation work. However, I found that the AI tools weren't very helpful for this complex, analytical task. This suggests that content strategy roles, which require higher-level thinking like strategic analysis and decision-making, could be a promising area for technical writers to specialize in as AI starts automating more routine writing. Fri, 06 Oct 2023 00:00:00 -0700 https://idratherbewriting.com/blog/content-strategy-safe-from-automation https://idratherbewriting.com/blog/content-strategy-safe-from-automation ai writing Open-source contribution myths, Hiring poets to train LLMs, Problems with 'content', AI agents (Oct 6, 2023) 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. Thu, 05 Oct 2023 00:00:00 -0700 https://idratherbewriting.com/blog/links-from-web-oct-6-2023 https://idratherbewriting.com/blog/links-from-web-oct-6-2023 ai writing news Embracing professional redefinition 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 <i>writer</i> 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. Tue, 03 Oct 2023 00:00:00 -0700 https://idratherbewriting.com/blog/embracing-professional-redefinition https://idratherbewriting.com/blog/embracing-professional-redefinition ai writing Documentation failures, Bestiaries, AI Explain post mortem, Inside TechComm podcast (Oct 3, 2023) 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.' Mon, 02 Oct 2023 00:00:00 -0700 https://idratherbewriting.com/blog/links-web-oct3-2023 https://idratherbewriting.com/blog/links-web-oct3-2023 ai api-doc news New article: AI and APIs: What works, what doesn't 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.' Thu, 28 Sep 2023 00:00:00 -0700 https://idratherbewriting.com/blog/ai-and-apis-what-works-and-doesnt https://idratherbewriting.com/blog/ai-and-apis-what-works-and-doesnt academics-and-practitioners ai api-doc api-doc-site-updates Claude versus ChatGPT -- and a few thoughts on using AI chatbots on an Alaskan cruise 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. Mon, 18 Sep 2023 00:00:00 -0700 https://idratherbewriting.com/blog/comparing-claude-vs-chatgpt-on-an-alaskan-cruise https://idratherbewriting.com/blog/comparing-claude-vs-chatgpt-on-an-alaskan-cruise ai Alphadoc: Build API documentation that tells your API's story A few weeks ago I mentioned <a href='https://alphadoc.io/?utm_medium=advertorial&utm_source=idratherbewriting&utm_campaign=techwriters'>Alphadoc</a>, 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. Sun, 17 Sep 2023 00:00:00 -0700 https://idratherbewriting.com/blog/alphadoc-question-and-answer https://idratherbewriting.com/blog/alphadoc-question-and-answer ai api-doc New API course topic: Using AI for summaries 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. Thu, 07 Sep 2023 00:00:00 -0700 https://idratherbewriting.com/blog/use-ai-for-summaries https://idratherbewriting.com/blog/use-ai-for-summaries ai api-doc api-doc-site-updates writing
https://feeds.feedburner.com/TomJohnson
feeds.feedburner.com
CC-MAIN-2023-50
26852
application/http; msgtype=response
sha1:B3BQ73ZZUACTTAGGZPCUKCBOL4T2XCTC
<urn:uuid:2cfb6867-d386-4dff-84d5-60e2f67037af>
2023-12-01T11:13:59Z
142.251.16.118
application/rss+xml
sha1:NMAEPWAGWAVD3QUUL3X6CI33UC24QXXR
<urn:uuid:4d4aa1d4-b2fc-4d5d-aa72-535d9ca0af1c>
https://feeds.feedburner.com/TomJohnson
response
<urn:uuid:0857e5d7-c0ab-4bc8-823c-e833234ac9a2>
isPartOf: CC-MAIN-2023-50
publisher: Common Crawl
description: Wide crawl of the web for November/December 2023
operator: Common Crawl Admin (info@commoncrawl.org)
hostname: ip-10-67-67-252
software: Apache Nutch 1.19 (modified, https://github.com/commoncrawl/nutch/)
robots: checked via crawler-commons 1.5-SNAPSHOT (https://github.com/crawler-commons/crawler-commons)
format: WARC File Format 1.1
conformsTo: https://iipc.github.io/warc-specifications/specifications/warc-format/warc-1.1/