More than words
Rachel Andrew ·
While I’ve done a lot of reference documentation writing, my favourite type of work is writing tutorials and “how to” content. I enjoy the challenge of understanding a technology and an audience, then explaining the technology to that audience. AI seems to be particularly bad at creating this kind of content. When people try, they ... More than words
While I’ve done a lot of reference documentation writing, my favourite type of work is writing tutorials and “how to” content. I enjoy the challenge of understanding a technology and an audience, then explaining the technology to that audience. AI seems to be particularly bad at creating this kind of content. When people try, they are often confused why it isn’t meeting their goals.
UX designers talk about the first run experience , the experience someone has as they use an app for the first time. For products and features aimed at developers, a getting started tutorial is often the first run experience. I learned this very clearly when I launched Perch, a small CMS product, back in 2009. Billing itself as a simple CMS, many of our customers had never installed a CMS before. Showing them how to go from a static HTML page to something their client could edit in a short tutorial was a huge selling point.
Whether you are selling a product or sharing a new web platform feature, if you can show the reader how to solve a real problem, with a minimum of steps and words, you can hold their interest. After that you can start to unpack things, provide more information and context, and deal with the more complex cases.
The majority of the time I spend writing a tutorial, isn’t spent writing. Before I put words on a page I need to understand the subject—the feature or product—well enough that I can explain it to someone else. Then I need to understand the audience. I’ll ask questions about who the ideal reader is, what they already know, and what problems they have that this product will solve. Understanding how to write is important, but the words are just the final step in creating content that will move people to action.
Knowing what to leave out is as important as understanding what to explain. An experienced writer won’t feel the need to pad their content with extra words, or attempt to show how much they know by describing every detail. They will write just enough to take the reader to the endpoint already defined.
Even before AI, writers have long been frustrated by people who don’t understand that the words are just the final stage of our work. We’ve all encountered people who assume we can drop in and make content that hasn’t been written with a real understanding of audience and purpose “good”. Generative AI means that people don’t even need to write the content they are foisting on weary technical writers, so there’s now a deluge of slop heading towards every technical writer with requests to “tidy it up”.
There’s been a lot of focus on AI “tells” in writing. These are very easy to deal with by ensuring your agent refers to a style guide, in particular for technical writing which tends to benefit from a strict adherence to a style guide. What is not easily fixable is when that content has been created without doing the research, without asking the right questions. Your AI tool can churn out words about what your product does, but unless you’ve already done all of the discovery work so you can provide that context to the agent, you’ll get a generic walkthrough.
This isn’t an anti-AI post, you can use AI to help streamline many technical writing tasks. However, if you come from a starting point of assuming the job of a writer is to write words, you will ask the agent to write words. You will get words, probably a lot of them, and then you will wonder why you aren’t achieving your goals. You might reach out to a writer, who won’t have time to fix the problem as they will need to go back and do the needed research. Even if they do have time, you probably won’t have time to wait for the solution.
The most frustrating thing is that it’s the first part of the process where AI can be most helpful. It can help you answer questions, do research, and pull together data much faster than has been possible before. The part where I write words is such a small part of what I do, that there’s not huge efficiency gains to be had there. When I do generate content using AI, I find that the requirement to check it for accuracy negates any time saved during the writing part.
I don’t think this is a new problem, I think AI has highlighted it due to the speed that content can now be created. Perhaps we writers need to rebrand ourselves with a new job title. However, if I have any advice to wrap up with, it’s this: if you are lucky enough to work with writers, bring them in early and include them in the conversations about goals for the product. Listen to them when they tell you where AI is most useful in their work, and where it really is not. If you are using AI in your writing, concentrate more on the research and goal defining part of the work, rather than the word-generating part. That way you can ensure what you write, however you write it, works for your reader and what you want them to do or learn.