[Prompt engineering series] Using file diffs for better release notes in reference docs

You can use AI prompts when creating biweekly release notes for APIs by leveraging file diffs from regenerated reference documentation. The file diffs from version control tools provide a reliable, precise information source about what's changed in the release. I also include a detailed prompt for using AI to analyze file diffs and streamline the release note creation process.

Updates two years later on my smartphone experiment

Two years ago, I started an experiment to reduce my smartphone usage. While I've reverted to using my smartphone regularly, I've learned a lot along the way. I've realized there's an inverse relationship between book reading and phone usage, and I've made a conscious effort to prioritize reading more books, especially with the reinforcement of book clubs. I've also accepted that while smartphones are necessary, it's the constant notifications that contribute to anxiety. By removing most social media and news apps, I've switched to a pull model for information, reducing my stress levels.

Thoughts on Docs as code being a broken promise

In response to Sarah Moir's post, *Docs as code is a broken promise,* I agree that Git's complexity can be a major hurdle for writers, especially when generating diffs for review. Simpler Git workflows and tools with visual interfaces for merging and diffs are essential for making the process smoother. Despite its challenges, I still prefer docs-as-code over proprietary tools because of its advantages, like using Markdown and generating diffs for review.

Get Better at Using Prompts With Deliberate Practice: One technical writer's little experiment — guest post by Diana Cheung
Get Better at Using Prompts With Deliberate Practice: One technical writer's little experiment — guest post by Diana Cheung

In this guest post, Diana Cheung explores how to learn AI by using deliberate practice to enhance her prompting skills. As a deliberate practice effort, she emphasizes intentional, systematic practice rather than mindless repetition, similar to how one would learn coding or other skills. In this post, she shares her attempts at using Claude.ai to work through editorial improvements to a GitHub project's API documentation.

Prompt engineering series: Creating scripts to automate doc build processes

Documentation scripts perform processes such as building reference documentation or doing other repeated processes with docs. This tutorial builds on the conceptual content in Use cases for AI: Develop build and publishing scripts. In this tutorial, I get more specific with strategies and techniques for prompts, walking through a prompt to build a script for generating reference docs.

What should your documentation metrics look like? Q&A with Zoomin about their 2024 Technical Content Benchmark Report
What should your documentation metrics look like? Q&A with Zoomin about their 2024 Technical Content Benchmark Report

Zoomin recently released a Technical Content Benchmark Report for 2024. This report explains the company's second benchmark report on documentation metrics, which analyzes data from 97.6 million user sessions across 136 countries. The report provides insights into average metrics like page views, bounce rates, time on page, GPT search usage, and more. In this Q&A with Rita Khait from Zoomin, she discusses how to interpret and use these benchmarks to set goals, improve content findability and performance, and demonstrate documentation's value to stakeholders and the business.

AI is accelerating my technical writing output, and other observations
AI is accelerating my technical writing output, and other observations

At the start of the year, I wrote a trends post and noted uncertainty about the directions AI will take tech writers this year. (See My 2024 technical writing trends and predictions.) Now that we're into April, I have a better sense of how things are going and wanted to provide an update here. My main observation is that AI is accelerating my technical writing output, making me about twice as productive as before. Also noted in this post: prompt engineering is a non-obvious skill that many tech writers still struggle with, even though documentation is more within AI's sights than creative content.

Upcoming conference: AI the API docs
Upcoming conference: AI the API docs

There's an upcoming conference called AI The Docs 2024: API Documentation and AI Best Practices, held April 3, 2024 online. The conference is put on by the same API the Docs group / Pronovix that holds other online conferences and events. I'll be one of the speakers. I'm planning to talk about prompt engineering.

Prompt engineering series: Gathering source input

A powerful way to reduce hallucination with AI tools is to supply an abundance of source material for the AI to draw upon. This article explores best practices for gathering and organizing that source material. I argue that you should be selective in what you include, preferring quality over quantity. Organize basic information first, then more advanced details. Include the reference output and any meeting notes.

Prompt engineering series: Error checking the output

In this article, I describe a method to use the AI to fact-check its own output against source materials. The better your source materials, the more likely you'll be able to identify errors. However, even with this method, human review by SMEs (subject matter experts) is still necessary. Unfortunately, getting SMEs to thoroughly review drafts can be difficult. Additionally, SMEs have such specialized knowledge, it's easy for one SME to LGTM a doc without having 100% certainty about each part.

Integrating AI with your content delivery platform and documentation: Zoomin Q&A with Keren Brown

In this post, I chat with Keren Brown at Zoomin Software about best practices for integrating AI with documentation. Keren emphasizes the importance of first making your content AI-ready, which means ensuring that it's accurate and up to date, before incorporating AI features. We discuss the reasons companies adopt AI, how to overcome implementation challenges, common mistakes, creativity vs. hallucination, consolidating content, user behaviors, security concerns, and measuring success.

Showcasing your API technical writer portfolio and projects — guest post by Peter Gustafson
Showcasing your API technical writer portfolio and projects — guest post by Peter Gustafson

How can you persuade potential employers about your API expertise? One of the strongest moves you can make is to share a link to your portfolio. The following is a guest post by Peter Gustafson, a technical writer who's had a lot of success with API documentation projects at many high-profile companies. I was chatting with Peter on Linkedin the other week about trends he's seeing in the field, and I asked him to write a guest post. In this post, he explains the importance of having an online portfolio that potential employers can easily access and browse.

Prompt engineering series: Reverse engineering the recipe for excellent documentation

I added another article to my prompt engineering series on reverse engineering prompts. Reverse engineering a prompt can mean a few different things, but in this article, I'm referring to deriving the likely prompt based on a given output. For example, you pass in some finished content and ask the AI to write a prompt that would produce a similar output. Although reverse engineering prompts might not be all that different from simply coming up with a template for docs, I added this article here to emphasize that you can get AI to write prompts for you, and many times these prompts are good. They can be much more detailed and robust than manually written prompts.

Prompt engineering series: Populating documentation templates using AI

I added a new article to my prompt engineering series on populating documentation templates. In the article, I explain how to use AI to populate documentation templates with information that you've gathered. This technique can be a quick way to get an initial draft of documentation, which you can then edit and review with SMEs.

Prompt engineering: Task decomposition and complex tree diagrams

I added a new article about task decomposition to my prompt engineering series. This tutorial will help you understand task decomposition by guiding you through the process of creating a complex tree diagram that’s too sophisticated for an AI tool to create at once.