Category: AI

Posted on

Is your documentation ready for AI?

AI just explained my own research back to me. I was surprised by how it showed me the message I meant to say 10 years ago, but seemed to lose in the academic genre of the original articles.

I’m working on how to teach AI tools in my API documentation course. As part of my research, I thought I’d feed some of my technical writing articles from about 10 years ago into an AI tool, along with some contemporary work from others. I asked the AI to compare, contrast, and summarize them from various angles.

The results were interesting enough that I had to write about them here.

When AI becomes your editor

One summary took an analysis I’d buried in academic prose and flipped it into something useful. It linked the different documentation types commonly found in API Documentation to what readers are trying to accomplish:

Original version:

In Using Readers’ and Organizations’ Goals to Guide Assessment of Success in Information Websites (2015), we proposed this list of goals that readers could hope to accomplish in an informational site (e.g. documentation). Examples of each goal were presented later in the 12-page article.

  • Reading to be reminded (Reading to do lite)
  • Reading to accomplish a task in a website (Reading to do here)
  • Reading to accomplish a task outside a website now (Reading to do now)
  • Reading to accomplish a task outside a website later (Reading to learn to do later)
  • Reading to learn (Reading to learn to use later or to apply with other information)

AI’s translation:

  • Recipes and examples for “reading to do now”
  • Topical guides for “reading to learn”
  • Reference guides for “reading to be reminded”
  • Support forums for edge cases and community help
  • Marketing pages for pre-usage evaluation

Then it got right to the point that I’d been dancing around for paragraphs:

Yet we typically measure them all the same way. Page views, time on page, bounce rate. That’s like using a thermometer to measure blood pressure. The tool works fine; you’re just measuring the wrong thing.

Ouch. But also: exactly.

The AI summary went on to suggest what matters for each content type:

Continue reading “Is your documentation ready for AI?”
Posted on

Looking back to look ahead

It’s been a while since I’ve contributed to my blog. The truth be told, I’ve been busy.

The day after my birthday, 2023, was when I found out that, along with 12,000 of my now former coworkers, I no longer had a job with Google.

I remember the feeling when I got the news (by email, of course). I felt like when I was learning to fly, and the instructor cut off the engine mid-flight. One minute you’re looking out the window, checking off the waypoints to your destination. The next, you’re looking for where you’re going to land. Because you weren’t going to be flying for much longer.

For the non-pilots reading this, most light airplanes keep flying after an engine failure. They just don’t stay at the same altitude for very long.

Learning to fly taught me that in those situations, the longer you ignore the reality of the situation, the shorter your list of options becomes. So, if they’re laying off thousands of people in my industry and, as we’d see in the months that followed, this would be just the beginning, I concluded that this was the end of my professional career as I had come to know it.

I was now gliding.

However, that’s a story for another post (or two).

A soft landing

The good news is (as it is for the pilots who are prepared for the possibility of an engine failure), my wife and I have landed safely and we’re doing fine.

My post-career landing was softened by an opportunity to teach an API documentation course at the University of Washington’s Professional and Continuing Education school. I just wrapped up the third term, last week, and it’s been a lot of fun.

However, the past two years have brought seismic shifts to technical writing, particularly in API documentation. Large language model tools have reshaped how we approach documentation creation, analysis, and maintenance. As practitioners, we’re all grappling with the same fundamental questions:

  • How do we adapt our established practices?
  • What assumptions about our craft need revisiting?

Enter AI and the curriculum challenge

Large language model (LLM) tools have taken the world by storm in the past two years. API documentation hasn’t been immune to their influence. As such, I’ve been working on an update to my API documentation course to integrate AI technologies to keep the curriculum current.

The challenge isn’t just adding AI tools to the syllabus. It’s understanding how these tools change the fundamental nature of documentation work. What skills remain essential? What new competencies do we need to develop? How do we teach both the power and limitations of AI-assisted documentation?

As I update the API documentation course, I’ve been putting different AI tools to the test, with some rather interesting results.

Continue reading “Looking back to look ahead”
Posted on

What did AI think of my recent article about AI?

In the process of writing A look at the past to see the future of technical writing, Adobe Acrobat’s AI assistant suggested that I ask it: Will AI completely replace human technical writers in the future?

What follows is the AI’s unedited 419-word answer to that question based on my 1,500-word article.

Based on the information provided in the document, it is unlikely that AI will completely replace human technical writers in the future. ​ Here are the reasons:

Continue reading “What did AI think of my recent article about AI?”