How we turned our writing guidelines into an AI colleague

In late 2022, OpenAI’s ChatGPT 3.0 sparked an AI revolution, and we seized the moment to enhance our technical writing. We set out to create an AI tool that not only enforces our writing guidelines but also streamlines content creation. Curious about if we succeeded? Read the blog and find out.

In less than two years, AI has become something ubiquitous that, much like the advent of the Internet in the 1990s, is gradually transforming how many of us work. According to OpenAI, ChatGPT alone reached around 100 million weekly users in just one year after launch, and 92% of the top 500 companies in the US are already using OpenAI products.

In other words, while the transition from an offline workplace to an online one took decades, the transition to an AI-augmented workplace won’t.

But a lot of individuals and teams struggle to put AI chatbots into practical use for various reasons. On the one hand, you’ve got human factors such as technophobia and a limited understanding of how they really work, but the large language models (LLMs) that these tools are based on also suffer from shortcomings such as making up answers on the fly and ignoring instructions, making them unreliable if used improperly.

The challenge, then, is coming up with a use case that doesn’t just sound cool, but also works in practice. Which is exactly what we set out to do.

Our challenge

The team I work in is mainly comprised of technical writers, a profession which works according to three basic tenets: Clarity, conciseness, and consistency.

Achieving consistency is tough when you’ve got 15 individuals with different backgrounds, writing styles, and degrees of experience writing technical documentation. Our guidelines and language alignment workshops certainly help, but they don’t solve the problem entirely since no two people write alike. Some focus on brevity, others on clarity. Some use contractions more than others. Some employ a friendlier tone. The list goes on.

To complicate things even further, we have a growing number of colleagues from other teams creating a variety of technical content for our products. We’ve produced training material and guidelines for them as well, but again, the best we can hope for is to mitigate the issue of inconsistency rather than eliminate it entirely.

In short, we needed something that could meticulously (and mercilessly) enforce our guidelines upon ourselves and help us write as uniformly as possible, much like how programmers use linters to automatically catch errors and stylistic deviations in their code before it goes into production.

We needed an AI technical editor.

Understanding large language models

Screenshot from an internal AI interaction.

While chatbot applications such as ChatGPT, Gemini, and Claude are colloquially referred to as ‘AI’, they’re specifically large language models, which are amazingly good at predicting what to say next, but that’s essentially it; an LLM-based application can thoroughly explain to you how the human kidney works if you ask it to, even though it doesn’t actually understand how the human kidney works. If you use these tools with the expectation that they possess any kind of inherent intelligence, you’re going to end up disappointed.

What LLMs excel at is quite simply generating text based on your instructions, or prompts. The quality of the output therefore depends a great deal on the quality of the prompt.

Put differently, it’s a tool which rewards you enormously for providing clear, concise, and consistent instructions.

There’s a considerable overlap in the skills required for a technical writer and prompt engineer. Both professions basically entail lots of ‘wordsmithing’, so we figured it would be easy to hammer out the perfect prompt for our AI technical editor.

It probably goes without saying, but it wasn’t.

Engineering our AI colleague

What we basically wanted was a solution where we could copy-paste a piece of writing into the chat box, hit Enter, and watch our AI technical editor generate a rewritten version with whatever necessary improvements that aligns the text to our guidelines. This would result in a dead-simple tool that 1) virtually anyone writing technical content at Axis could pick up and use right away and 2) help us write in a single, consistent voice.

To achieve this, we’d need to draft a set of custom instructions for our internal (and on-premises) AI to keep in mind every time we interact with it. And to help us come up with a decent set of instructions, we naturally went with the spirit of the times and enlisted an AI assistant.

We started by assigning our chatbot the role of an expert prompt engineer. Its task was simple: To help us craft the perfect custom instructions for its future role as a technical editor.

After quite a bit of back and forth, we came up with something that seemed to contain all the components of a great prompt:

• A persona
• The context
• The task
• The output format
• Examples

Included in the context were our guidelines, which we made it convert into a style guide with a format and language that was more LLM-friendly.

It’s alive!

We bid a fond farewell to our AI prompt engineer and inserted the custom instructions it had helped us create for its final form: The technical editor.

We began to test it out by copy-pasting in random sections from Axis user manuals. It proceeded to rewrite in seconds what would have taken a human tech writer far longer. We suddenly had a tool that was doing a key part of our job for us, and much more efficiently than we ever could.

Of course, there were a few issues. We didn’t always agree that the rewritten version was necessarily better. It would also frequently ‘forget’ to follow some aspects of its style guide, and sometimes, it would completely mess up the output format.

We were off to a great start, but unsurprisingly we didn’t hit the bullseye on our first try. What followed was a long (and ongoing) process of optimizing our instructions. It’s already capable of providing great feedback on our writing, but it’ll have to wait a little longer for that promotion to technical editor.

What the future holds

I’ve hopefully given you a small glimpse into the kind of projects that have been going on in countless other content-creating teams around the world since November 2022. This isn’t the only use case we’ve discussed for AI, either. It can potentially also help us write API documentation, manage terminology, and help us with scripts in our authoring tool, for example. Further down the road, end users might even be able to ask a chatbot for information they would otherwise have to look up in our user manuals.

Before I became a technical writer, I was a translator for nearly a decade and saw how AI gradually transformed the translation industry. Computer-assisted translation tools (CATs) went from being treated as a gimmick to a requirement. I also began studying web development around the time ChatGPT 3.0 launched. Back then, experienced web developers were unimpressed by its coding abilities, but as LLMs have become increasingly sophisticated, more of them have started to use these tools in their daily work – and it probably won’t be long before they become a requirement in that field, too.

I have no doubt that the field of technical writing – and every other type of knowledge work – is on a similar trajectory in relation to AI; it’s not a matter of if, but when it will transform how we work.

What this transformation will entail in practice remains to be seen, of course. But in the meantime, it’s probably a good use of your time to start getting acquainted with these tools.

---

Would you like to work with these kinds of things too? We are constantly looking for skilled engineers to join our team and the rest of the company. Please keep an eye open on our career page or check out any open positions here.