Can you spot what’s wrong with these documentation processes?
We’ve created three short, interactive exercises that put you in the technical writing reviewer’s seat.
Each exercise presents a Slack conversation about a documentation project. Your task is to work out what has gone wrong and identify the type of problem each message reveals.
They’re designed to test your judgement on issues such as ownership, review processes, source-of-truth problems, maintenance, and collaboration.
There’s no login or details you need to give in order to try these out.
Exercise 1: Documenting a new API endpoint
A team is working out how to document a new API endpoint.
Read the conversation and tag each message according to the problem it illustrates.
Spot what’s wrong with this API documentation process
Exercise 2: Keeping chatbot content up to date
A team discovers that its support chatbot has started giving customers outdated answers.
What went wrong with the way the chatbot’s source content was maintained?
Read the conversation and identify the problems.
Spot what’s wrong with how this chatbot is maintained
Exercise 3: Three teams document the same feature
Three different teams have documented the same feature — with rather different results.
Can you identify the process and governance problems that allowed this to happen?
Spot what’s wrong with how this feature got documented
How did you do?
Were the problems obvious, or did some only become apparent once you looked at the whole conversation?
These exercises highlight an important point: documentation problems are rarely just writing problems. They often begin much earlier — with unclear ownership, weak review processes, duplicated sources, poor communication, or nobody being responsible for keeping information up to date.
That is why effective technical writing involves not only creating clear content, but also designing a reliable process for creating, reviewing, publishing, and maintaining it.
How many of the problems did you spot?
Leave a Reply