New API doc course topic: Using AI for language advice

I added a new article to my API doc course on using AI for language advice. When you have questions about style, grammar, or other syntax, try asking your favorite AI tool. AI tools can do an excellent job at identifying the particular grammar or style rule or reason, and they can provide guidance about why one phrasing is preferable to another. In asserting a preference, AI will often make a convincing argument for one style over another, such as noting that a word could be interpreted in different ways and so is more ambiguous than the other phrasing.

New API doc course topic: Using AI to create doc updates based on bugs

I added a new article to my API course about using AI to create doc updates based on bugs. By bugs, I'm referring to small issues often surfaced by users about the docs. Bugs are often long lists of random fixes to make with the docs, often involving a small number of changed lines. However, interpreting the bugs can be challenging. Fortunately, AI tools can help you understand the issue and resolution.

New API doc course topic: Using AI to learn coding

I added a new AI topic to my API doc course: Using AI to learn coding. One challenge API technical writers face is understanding developer code and tools. This is by far the most intimidating aspect of being an API technical writer. As if documenting code for one project weren't enough, API technical writers must also support multiple projects simultaneously, often with different types of code. You might document a Java API for one project, a REST API for another project, some Go code for an SDK, some C++ code for another project, and so on. It can be nearly impossible to be fluent in all of these languages. Fortunately, you can use AI tools to learn code more efficiently. AI tools can act like a friendly programming buddy who is sitting next to you, ready to explain anything you want, at whatever technical level you need. You can zero in on a specific question or broaden it out to increase your understanding from ground zero.

New topic in API course: Using AI tools to write build and publish scripts

I added a new article to my API doc course about using AI tools to write scripts. At the core of API documentation work is building, staging, and publishing of API reference content. Whether it’s Javadoc, Doxygen, OpenAPI, or other reference output, almost every API has reference documentation that you build, stage, and publish with each release. Given the centrality of documentation building and publishing tasks, AI tools can be a great help when it comes to configuring scripts to perform these tasks. This is one AI area few people are focusing on, but scripts are an easy way to incorporate AI to improve your productivity and reduce the tediousness of document production.

New topic in API doc course: AI document engineering with pattern-based prompts

I added a new section to my API doc course on pattern-based prompts. Pattern prompting involves teaching the AI a specific structure or template, then having it populate information into that template. Pattern prompts are similar to few-shot prompts, but in this case, rather than having the language model populate the template with its own information, we’ll have it sort and structure a mess of information into the template, thus reducing hallucination and error.

First Look at Oxygen XML's Positron AI Assistant [API doc course]

I added a new topic to my API doc course on the Oxygen XML Positron Assistant. Positron lets you use AI tools inside Oxygen XML to help with a variety of writing tasks, such as writing short description elements, correcting grammar, improving readability, adding index terms, and more. Positron hooks into an AI provider (currently ChatGPT 3.5) to pass your topic content to the AI with a specific instruction. It then returns the content and allows you to preview the diff, seeing what has changed and inserting the modified text in place. By integrating directly with your project, Positron helps you use AI when and where you need it, without switching contexts or resorting to external tools.

Adding a new AI section to my API doc course

I'm adding a new section on AI to my API doc course. Currently, there are just two articles in there (one on Oxygen XML's Positron Assistant, another on AI document engineering) but I plan to add many more over the coming months.

First look at the Oxygen XML's AI Positron Assistant

The Oxygen XML Positron Assistant lets you use AI tools inside Oxygen XML to help with a variety of writing tasks, such as writing short description elements, correcting grammar, improving readability, adding index terms, and more. Positron hooks into an AI provider (currently ChatGPT 3.5) to pass your topic content to the AI with a specific instruction. It then returns the content and allows you to preview the diff, seeing what has changed and inserting the modified text in place. By integrating directly with your project, Positron helps you use AI when and where you need it, without switching contexts or resorting to external tools.

Telling your conversion story into tech comm

One of the classic stories that is told in our profession is how and why we got into technical writing. The story is usually one of unintended directions and decisions, in which someone initially intends to pursue one career, makes a series of adjusting decisions and course corrections, and finally ends up writing docs as a tech writer. Because so few people actually set out to become tech writers, the story is usually interesting to listen to...

Chapter PDFs for API doc course

I made some updates to the PDF options for my API doc course. Previously, I had one massive PDF that was 900+ pages. I split that long PDF into chapter PDFs instead, making each chapter PDF about 50-75 pages in length. I also put the chapter PDFs into the Buy Me a Coffee Shop digital downloads feature and priced them at $3 each or $20 for all.

How to meet other technical writers in Seattle -- WTD Seattle coffee chats

I routinely run into tech writers in Seattle who have never heard about Write the Docs Seattle, which is a local meetup for the larger Write the Docs (WTD) organization. The WTD Seattle meetup is publicized through meetup.com and includes an organizing host who facilitates welcoming and discussion among the members. Currently, WTD Seattle is holding monthly coffee chats referred to as “Casual Caffeine Hour” events. These events are held in th...

How the blog-to-book experiment is going: challenges and thoughts

In this post, I explore the challenges of transforming a blog series into a book. The process proved to be more complex than I thought, and I had to deal with inconsistencies around tense (present vs past tense), time management, momentum, and more. Trying to read through 70,000 words to see if it had the shape and arc of a book was no small feat, and is one I'm still wrestling with.

Blog and API doc course are now one site

I've been a bit quiet on my blog lately because I've been focusing on some technical upgrades. They probably aren't that noticeable, but I recently merged the blog and API doc site into the same code base. Working from a single code base will make site enhancements much easier in the future.

Doctave Q&A with Niklas Begley

Doctave is a new docs-as-code SaaS documentation platform built on Rust. In this post, I ask co-founder Niklas Begley more questions about the origin behind the platform, differentiating features, approaches to common problems, and more. If you're looking for a docs-as-code platform that will allow you to get productive with documentation authoring quickly, Doctave looks to be a promising solution.

News turns the content wheel of advertising

I recently tried a new approach to my newsletter: summarizing news articles. The new approach resulted in good engagement but left me feeling empty. News exploits our psychological vulnerabilities, including our novelty bias, negativity bias, and fear of missing out. We should be mindful of our news consumption and balance it with other more self-directed activities.