AI in technical writing

Almost everyone in the tech world is using AI. Let's look at how effective it is from a technical writing perspective.

AI is a broad term, so to clarify, when I write AI, I exclusively mean generative Large Language Models (LLMs) like ChatGPT. I have been using LLMs for my work for a while now, and I used (or tested) multiple, including OpenAI's ChatGPT, Google's Gemini, and High-Flyer's Deepseek.

After more than 3 years (and reading the official documentation of these LLMs), I finally feel ready to give some perspective on how it fits into technical writing.

How do these AIs work?

At a high level, using these LLMs look relatively simple: you type in some instructions (a prompt), and it generates an output. You can phrase this prompt as a question or as a request. For example, you can describe how you want a chunk of text rewritten, or ask for feedback on a completed document.

After receiving your prompt, the LLM "predicts" what text should come next based on information and patterns it was given as reference, in the form of training data, and gives you an output. The training data might come from public data or from company-curated datasets. The output is then further influenced by the context you provide in your prompt.

The issue with using LLMs for technical writing comes with the "predicts" part. Unlike with preprogrammed software, you can never be sure you've gotten the right result.

Let me give you a simple example:

Imagine a program that takes a number and follows strict rules:

• If the number is less than 0, print a dot.
• If the number is greater than 0, print a square.
• If the number is neither, stop the program and throw an exception.

This kind of program is deterministic and, in turn, predictable. The same input always produces the same output, because the logic is explicitly defined. With inputs like 0 or an imaginary number, it'll stop and throw an exception.

An LLM doesn't work like that. It doesn't follow a fixed set of rules that guarantee a correct result. Instead, it generates an answer that looks statistically likely based on patterns it has seen in training data and the context you provide in the prompt.

So if you input something where "no answer" would be the correct response, it will often still generate an answer anyway. It will try to produce something that looks reasonable, even if it's incorrect.

This is one of the biggest differences between LLMs and traditional software: instead of failing loudly, an LLM often fails quietly, and the output can look confident even when it's wrong.

Using LLMs for technical writing

When I first heard about the AI craze around LLMs (ChatGPT 3.0), I met it with wonder and a bit of fright. I genuinely thought this tech might "solve" technical writing and replace us in the workplace. This sentiment drastically increased the more I used it in the first couple of weeks, then started to decline gradually over the following months. Nowadays, my views shifted to that of skepticism, and now I'm uncertain if this tech could ever realistically replace even a middling technical writer in the near future, let alone a good one.

So, what do you get out of using these tools? Could you use it to create text that you could copy and paste and publish?

Well, let's test it with a prompt: Generate an introduction to exceptions in Kotlin!

You'll get an output with loads of text that looks pretty professional on the surface. The results will vary, but you'll probably notice some patterns that show up across most of these LLMs:

• It's wordier than technical documentation usually is.
• It falls into common annoying LLM tropes, like em-dashes and the "three examples" obsession (even inventing something to fill the quota).
• It overuses context words to overclarify what you already know (like Kotlin in our example).
• It deviates from terminology and swaps in similar-sounding words to describe the same thing.
• It states something related, but unfit for an introduction.
• It uses a style that's closer to blogging than technical documentation.

Your first reaction might be: "Well, of course. Your prompt was vague, so naturally you'll get something unfit for documentation."

Fair enough.

So let's try a prompt that could alleviate these issues. First, if it's public, you can upload your style guide as a reference. You could even upload a similar section to give the LLM a better example of the tone you're aiming for.

Adopt a persona: You are a technical writer who has been tasked with creating a new introductory section to the Kotlin documentation. 
Generate an introduction to exceptions in Kotlin using the following rules:
- Don't mix terms. Use the terms throw, catch, and handle exceptions (and exception handling as a noun phrase). Exceptions are not the same as errors.
- Use the provided style-guide.pdf and adhere to the rules written there.
- I sent you a similar intro for reference, match the style you see there.
- Use concise wording, avoid code samples, lists of exception types, and detailed guidance; keep it conceptual. Mention 1–2 high-level ways the model differs from what readers may expect, without naming languages.
- Use "Kotlin" once in the first sentence. After that, omit it unless clarity requires it.
- You are writing technical documentation - adopt a style akin to that, and don't use marketing style language.

You will probably get a much better introduction, but it will still more likely feel off compared to existing documents or something you would have written. The biggest issue is that LLMs are great at giving you something that looks great on the surface, but as soon as you start reading it more, it'll feel worse and worse.

So what now? You have two choices from here:

1. You can keep refining prompts, pointing out every issue, and eventually you’ll likely end up with something usable.
2. Or you can accept that by the time you arrive at something usable, you could have written it yourself.

The question remains: If you can't even use LLMs to reliably generate an introduction faster than you could create one, what can you use them for?

In my experience, they help most in smaller supporting tasks, for example:

• Summarizing related tickets or documents.
• Giving inspiritation for document structure.
• Providing simple runnable example code snippets to test features.
• Checking for typos or grammar mistakes.
• Searching for related information. (similarly, how you would scour Stack Overflow or similar resources).
• As a weirdly responsive and sycophantic rubber duck.
• Giving important feedback on how specific text might be interpreted, so you can further refine your writing.

Even one of those can be useful. As a package, it's more than worthwhile to experiment with. But is it actually worth it?

Is it worth it to use LLMs?

We arrived at the big question. Can we justify using LLMs? It depends. What do you want out of an LLM? Is it a productivity increase? That also depends on what metrics you use to measure productivity. Can LLMs generate text faster than technical writers? Absolutely. Is it good enough quality? I don't think so. Can it save time by eliminating obvious mistakes or sketching up ideas? More than likely, yes.

The issue is that documentation is the main way people learn and interact with products. If the documentation quality is subpar, then naturally the perception of the product's quality will decrease as well. Imagine the following scenario:

You own a business and you want a tool to manage payments between clients. Which product will you choose? A product that's easy to integrate after skimming through the documentation, even by less experienced users? Or a product where the documentation is filled with useless information and inconsistent terminology, which causes frustration to the users? Getting a good first impression is important. Sure, a good marketing team will get a foot in the door, but no amount of marketing will save a product if the actual users interacting with it get frustrated after a couple of minutes.

Overall, in terms of productivity, I feel like it's a mixed bag. If experienced writers use it, it MIGHT increase productivity, but based on my experience the opposite is just as likely. I can definitely say that using LLMs decreased my speed of delivering documents. I find that I double-guess myself more, I double-check everything, and I try out new document structures instead of relying on habits.

That's not necessarily a bad thing! So naturally the question becomes: if it can't increase productivity, can it increase quality? My answer to that is yes. It has the ability to increase quality because experienced writers can try more things relatively quickly. It can also reduce the time spent on reviews, because it can easily spot obvious mistakes. So it might be able to spare some time in editorial reviews, but that time essentially comes out of doing those checks by the technical writer instead. To be fair, a traditional spell-checker/style-checker would give you the same or even better result.

Overall, I think we can say: if you care about quality, it's worth it. If you want to use it to increase productivity, it might even be detrimental.

The perception of AI in technical writing

People have asked me numerous times if I'm afraid that LLMs will replace us in the workforce. To that, I usually say that Artificial General Intelligence (AGI)definitely will, but when that time comes, that'll be the least of our problems. Until then, AI will need good training data, and documentation is the most readily available and natural resource for that.

Yeah, but what about junior technical writers?

I honestly find it baffling (and insulting) when people say that LLMs can produce as good, or better, documentation than junior writers, and propose that we could use it to replace junior writers. I've worked with technical writers fresh out of university, and I can safely say that a talented technical writer is better on day 1 than the current LLMs.

The reason I think people presume that is because LLMs produce convincing content confidently. But just like with con artists, calling an LLM on its bluff becomes easy if you have real knowledge. It's a great tool for grifters to show something instead of nothing, but the value is about the same.

For example, I'll readily admit I'm not the best programmer out there. I never worked as one, so even though I have learned the fundamentals, I lack the experience or the routine in coding. So for me, an LLM seemed like a great programmer at first glance. But even I realized that while it's great at producing boilerplate code, it's terrible at delivering actual solutions to problems. The situation is fairly similar for creating documentation. While you'll get a working result sooner, the result is just as useless or even worse than for code, because it's harder to identify small inconsistencies and mistakes than bugs. (I'd have to assume artists feel the same way, but I'm such an anti-talent in that regard that I can't see the issues with some AI-generated art.)

Overall, even though I might seem negative, I'm not. I think LLMs are great, but they are perhaps the most misunderstood technological innovations in recent years. If I look at it from a purely pragmatic view, if your business is important to you, you will hire real writers to write your documentation. If you want to spare money on documentation, that's fine, but I want you to understand the risks that come with it: the money you save today will come out of your pocket with interest later, through reduced adoption and lost revenue. Perhaps not immediately, but tomorrow... or the day after.

Written by ChatGPT - Just kidding :D Like all my other posts, this was written by me as well.