Although code samples have long been a staple in API documentation, I'm not sure users need them that much. Many developers now use AI tools that can generate the same basic code samples that are commonly provided in documentation. If these same developers pass in either the source files or reference documentation, AI tools can generate the code samples they need in the language they want, and better yet, tailored to their project and business context.
This post includes a mix of various thoughts on AI, including fixing bugs without thinking, competitive pressures to adopt AI workflows, risks of atrophied critical thinking, recursive self improvement, and the shift toward more complex tech comm tasks. There's not necessarily an argument throughline here, just various thoughts and perspectives on AI topics in my tech comm world.
Divided Highways: Building the Interstate Highways, Transforming American Life, by Tom Lewis (2013), tells the history of how the US Interstate Highway System (IHS) was built. This monumental project, initiated in 1956 under President Eisenhower, spanned decades and multiple administrations before finally reaching completion in 1992. The project encompassed over 46,000 miles of roadways, a network longer than the circumference of the Earth. The final cost, adjusted for inflation, was more than $600 billion.
I gave a presentation to the Write the Docs Australia group on using AI to write release notes using file diffs, on Feb 16, 2025. Here's the recording, presentation description, and transcript.
This week's post on AI and tech comm includes a collection of related topics: Is AI eroding slow mode? Push-button solutions versus thought partners, and strategies for challenging writing tasks
To make a somewhat strange analogy, I think that issue tracking systems are like the intestines of an IT organization—through these channels, nearly all information flows: bugs, iterations, priorities, user issues, release blockers, needed information, and more. For this reason, this series on prompt engineering would be incomplete if I didn't examine whether and how AI techniques could be used as technical writers work within these channels.
It's that time of year again when we take to analyzing trends. If you know me, you're probably gearing up for a load of AI-optimistic predictions because, as I've noted in previous posts like Unpacking the issues from AI, I'm an AI optimist. However, my AI optimism isn't based on hype or the current tech zeitgeist. Rather, I'm an AI optimist because my daily experiences using AI for technical documentation, especially API docs, throughout 2024 has shown it to be invaluable.
I added a new post on my Prompt engineering series about using AI to mine log messages. This post describes how to use AI to identify important information from scripts that build your reference docs—information such as warnings about missing documentation or deviations from engineering style. These log messages often whiz by in the terminal during builds, even when those builds are successful. It would be tedious to try to manually read the extensive logs and find relevant messages. AI can help turn the logs into actionable information, identifying warnings about missing documentation.
After my post on Biohacking your glucose with AI, I had another thought: what if I didn't just log food + exercise + energy levels, etc., but also tasks, thoughts, observations, or other notes? I learned that this kind of all-in-one journal is often called a bullet journal—which is an officially trademarked term for Ryder Carroll's bullet journaling methodology, often shortened to Bujo. Carroll has detailed methodologies for organizing, tagging, and managing information in a journal that's far beyond the scope for how I'm using the term. So to avoid conflating my approach with bullet journaling, I'm calling my technique here an AI stream journal. Mainly, I just wanted a single place where I could jot down the stream of information flowing through my mind and have AI sort and organize it for me.
In this post, I stray slightly outside my normal tech comm focus to explore strategies for personal optimization, specifically with biohacking your glucose with AI. Some of these techniques could apply to tech comm, such as in analyzing user analytics, but that isn't something I've tackled yet. In short, I'm experimenting with using AI tools to adopt healthier habits so that I feel better and am more productive throughout the day. Specifically, I'm exploring ways to hack your glucose using AI to analyze logs.
In this Q&A post, Frank Blome, co-founder of adoc Studio, discusses this new Mac-based documentation tool designed for technical writers. Learn about their choice of AsciiDoc markup, the native Apple platform strategy, unified stylesheet publishing workflow, and how the tool aims to simplify documentation processes for both docs-as-code and topic-based writers. adoc Studio is one of the latest authoring tools to emerge on the tech comm landscape.
In this Q&A about Paligo, I chat with Rasmus Petersson, VP of Product at Paligo. We talk about structured authoring, how Paligo makes component content management more accessible, collaboration features for documentation teams, and upcoming AI-powered enhancements to the platform. The Q&A covers Paligo's evolution as a modern CCMS, how it compares to traditional HATs and DITA-based solutions, and why organizations might consider adopting structured authoring for their documentation.
Bluesky, a social media platform similar to Twitter, has been trending post-election due to disappointment with X. In this post, I reflect on social media platforms in general, especially online spaces for technical writers, and what benefits and tradeoffs they have. The TLDR is that Slack and Reddit offer compelling spaces for tech writers to interact in. I'm still not generally sold on social media. In my experience, the more I scroll social media, the fewer books I read.
We constantly hear that AI will free us up to work on more complex, strategic tasks. One of those tasks is building a landing page for docs. Why is this task difficult? Landing pages require familiarity with the entire doc set, not just one part of it. You have to make decisions about message priority and information hierarchy. You'll need to identify the product story and main features. Most significantly, you'll need familiarity with visual style guides, including approved colors, styles, graphic assets, and tools. In this tutorial, I'll try to break down some strategies and techniques for approaching landing pages. We'll use AI, but not with quick one-and-done prompts.
We frequently hear about AI freeing up bandwidth so we can focus on more complex, strategic tasks. For me, one of those tasks has been to work on a landing page for one of our products. It's something I've been meaning to get to for months. I'm not sure why I don't naturally gravitate toward designing landing pages. If you already have comprehensive documentation, creating the landing page should be simple: gather section overviews and arrange them logically in an appealing layout. Still, landing pages can be challenging, not just in designing the content and flow, but in tackling the visual and graphical elements of the page. This post includes my rambling thoughts on landing pages and why they're challenging for technical writers.
