My AI has a sense of snark

This weekend, I woke my LinkedIn profile from its hibernation and spent some time bringing it up to date and dusting off the cobwebs. The good news is that it gave me something to blog about!

I sent my profile into hibernation last fall for a variety of reasons. The main reason was just to come up for air as I found the constant barrage of “inspirational accomplishments” and “incredible journeys” overwhelming. Sprinkled with incredibly sad stories of people having to sell their houses after months of unsuccessful job hunting, made it just too much of an emotional roller coaster ride.

No offense to anyone who’s managed to accomplish anything during these difficult times. And my heart goes out to everyone who needs a job and is still struggling to find one. But I needed to step away from the notifications for a while.

Well, times up! I’m back online and I’m here to write this, let’s call it a, celebratory post.

Back online

To kick things off, I’d need some content for LinkedIn (as is the nature of the site), so I asked Claude (AI) to write a blog post about the style of LinkedIn posts in the style of a LinkedIn post. This is a task for AI because it’s not natural for me to write in, or about, the genre.

Unfortunately, I might have confused it. The AI was working in the context of my blogging-style prompt and you can see how it tries to follow my blog-post style while analyzing LinkedIn accomplishment theater, and while trying to make the post itself LinkedIn-worthy.

What follows is the AI-generated post that I wished I could have written.

I just published a blog post, and you won’t believe what happened next

Yesterday, I sat down to write a simple blog post about content strategy. What started as 800 words of practical advice somehow transformed into a LinkedIn-worthy tale of professional triumph that would make a motivational speaker weep with pride.

Here’s how it happened (and why we should probably talk about it).

July 28, 2025July 28, 2025

Teaching technical writing in an AI world

A lot has changed in tech writing during the past two years when it comes to LLM tools (a.k.a. AI). That time frame coincides with my tenure teaching API documentation and watching how my students adapt to these tools has given me some insight into how our profession is evolving.

More to the point, it’s forced me to develop a systematic approach to AI integration for my next course.

The challenge: Teaching moving targets

When I started teaching API documentation in spring 2024, LLM tools felt like the “Apple II” stage of PC evolution. Interesting, but not quite ready for serious work. My students were “cautiously skeptical,” and treated AI as a curiosity rather than a necessity.

Some students used LLM tools to help create rough drafts while others wanted to avoid the AI tools to get a more hands-on experience.

That changed rapidly. By the third course, students weren’t asking whether to use AI, they were asking how to use it effectively. The industry had moved very quickly, and my students needed practical frameworks, not philosophical debates, to confront this new reality.

What I learned from watching students evolve

Rather than ban AI tools, I decided to lean into them and watch what happened. I asked students to describe if, and how, they used AI tools in their assignments. This gave them a record for their portfolio presentations, but it also created an informal longitudinal study of AI application in technical writing education. Here’s a summary of what I observed:

July 26, 2025July 26, 2025

When AI fixes everything (except what matters)

Imagine that you’ve deployed AI to generate your technical documentation. The tool promised to revolutionize your content workflow, and honestly, it delivered on speed. What used to take days now happens in minutes.

Now, fast-forward six months to find customer support is drowning in confused user tickets. Social media mentions of your product are increasingly sarcastic. Sales is asking pointed questions about why adoption rates are dropping, and nobody can figure out what changed. The product is as solid as ever.

In this post, I want to provide a more optimistic outcome and follow up on a recent post that ended on a scenario that could lead to such a story.

The invisible problem

When you don’t have reliable documentation analytics, problems announce themselves through every channel except the actual source. Without reliable analytics, your first clue that AI is producing unhelpful developer docs won’t be a dashboard alert. It’ll be angry developers posting screenshots of your broken code examples on social media.

Remember, automating your processes accelerates them in whatever direction they were already heading. If your current documentation process and performance are unmeasured and reactive, you won’t know if AI is helping you out or not, until long after the damage has been done.

It just keeps producing content that checks all the boxes while serving no one.

A different path forward

The dystopian scenario above isn’t inevitable. But it requires resisting the “deploy AI everywhere immediately” impulse and taking a more methodical approach.

July 22, 2025July 22, 2025

Do-it-yourself (with a friend) portfolio

Everyone tells aspiring tech writers to find an open-source software (OSS) project to create content for a portfolio. Unfortunately, while popular advice, I haven’t heard that to be very successful.

Rather than leave you hunting for those elusive OSS opportunities, I’ll describe how the portfolio project I use in my API documentation course works. This approach might be more accessible and achievable for building the portfolio content that you need.

The course portfolio project works because it addresses two critical elements often missing from solo projects: collaboration and accountability. Both are essential skills for technical writers, and both significantly improve your chances of producing something portfolio-worthy.

How to run your own portfolio project

Here’s how our portfolio projects work, as adapted for self-directed learning:

July 19, 2025July 19, 2025

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:

July 13, 2025July 13, 2025

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.

March 18, 2024

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:

March 18, 2024July 22, 2025

A look at the past to see the future of technical writing

Out of pure coincidence, I stumbled across this blog post about Technical writing in 2049 by Fabrizio Ferri Benedetti as I reviewed some examples of my earliest technical writing. I thought this might be a good opportunity to reflect on the past to see into the future.

My oldest artifact of technical writing that I authored is a technical manual for a central patient monitoring system I built for a hospital in 1981. The oldest technical manual I could find in my library is an Air Force training manual from 1952. I’ve kept some other relics of technical writing, but most are still in boxes.

Fabrizio’s blog post ends with this line, “What do you think tech writing will look like in 2049? I’d love to hear your predictions!” With my historical artifacts in hand, I accept his challenge and offer this response.

While I can only imagine what I thought about the future in years past, I can use these artifacts as examples of where technical writing has been and where it might go. I can also use them to describe how hard it is to predict the effects of a technical disruption, except by saying, “The more things change, the more they stay the same.”

Tech comm 1999

25 years ago, we still mostly printed the tech docs in books, as we had done in the decades that preceded, although online documentation was clearly about to make its debut. For a short while, CDs replaced printed docs but soon after, tech docs were almost exclusively served online. Could I have imagined online docs in 1999? Probably, without too much imagination. After all, we already had AltaVista.

To look at the past, present, and the future of technical writing, I think it’s best to tease that apart into content, production, and use or audience.

I’ll leave out stakeholders, because I haven’t seen that change much since content went online and the business model for technical writing all but disappeared. That’s a conversation for another article.

April 4, 2022April 4, 2022

Tips for conducting documentation research on the cheap

In my previous post, I presented some experiences with testing and the resulting epiphanies. In this post, I talk more about the process I applied.

The process is simple, yet that’s what makes it difficult. The key to success is to take it slow.

The question

Start with something simple (and then simplify it). Your first questions will invariably be too big to answer all at once, so think, “baby steps.”

Instead of asking, “How can we improve our documents?” I asked, “What do users think of our table of contents (ToC)?” Most users don’t care about how we can improve our docs, unless they’re annoyingly bad, so they don’t give it much thought. They do, as we found out, use the ToC, and we learned that it wasn’t in a way that we could count.

The sample

Whoever you can get to sit with you. Try to ask people who are close to your target audience, if you can, but anyone who is not you or in your group is better than you when it comes to helping you learn things that will help you answer your question.

The process

Listen with a curious mind. After coming up with an answerable question, this is the next hardest thing to do—especially if people are reviewing something that you had a hand in writing or making.

Your participants will invariably misinterpret things and miss the “obvious.” You’ll need to suffer through this without [too much] prompting or cringing. Just remind yourself those moments are where the learning and discovery happen (after the injuries to egos and knees heal, anyway).

When the participant asks for help, such as, “where’s the button or link to do ‘X’?” A trick I learned from more experienced usability testers is to ask them, “where do you think it should be?” That way you learn something about the user experience, rather than just finishing the task without learning anything. If they’re still stumped, you can help them along, but only after you’ve learned something. Remember, you’re there to learn.

April 3, 2022

Documentation research requires more curiosity than money

Sure, money helps, but success doesn’t always correlate with dollars spent.

Here are a couple of examples that come to mind from my experience.

piClinic research

My favorite research success story (perhaps because it turned out well) occurred while I was researching the piClinic project. While on a medical mission to a rural clinic in Honduras, I saw a mountain of paper patient records with a lot of seemingly valuable information in them that could never be tapped. Clearly (to me) computerizing those records would improve things. I felt that, based on my first-hand experience, automating record storage would make it easier to store and retrieve the patient records.

It would, and later, it did.

But…

When I later actually sat down and interviewed the target users and watched what they did during the day and, more importantly, during the month, I learned that what I thought was their biggest obstacle, storage and retrieval, was not really a problem for them.

It turned out that the real time-consumer in their process was reporting the data to the regional health offices from these documents. Each month, each clinic would spend 2-3 days doing nothing but tabulating the activity of the clinic in their reports—something I hadn’t seen for myself in my earlier, more limited, experiences.

My assumption that storage was the problem to solve died during that research. So, I pivoted the design of the piClinic app to focus on reporting (as well as the storage and retrieval necessary to support that) to reduce their monthly reporting time from days to minutes.

Docs by Design

Posts