We’re going to be running a technical writing course for a client where the delegates are from the Support department. This means we have had to consider what we should teach Support staff about technical writing.
We sent the delegates a pre-course questionnaire, asking them what they’d like the course to cover. I thought it would also be useful to ask on Social Media for other people’s opinions. I expected people to focus in on topics like findability, tagging and metadata, but neither the delegates or the respondents on Twitter, LinkedIn and Slack mentioned this.
Here are some of the replies on Social Media:
Tech writers are normally very user focused. Technical support staff can be, but often are not – they are incentivised to close tickets, not to think as the user. That can run to the documentation they create (or don't create) for their colleagues.
— Rob Woodgate (@agiledoc) November 10, 2020
There are many parallels between technical writing and case resolution process! I like to highlight the skills and experience they already have that they just need to transpose into a different workflow/output.
— Sara Feldman 🤔 (@Sara_inquirer) November 10, 2020
Be sure to remind them that support issues point out areas where the techwriting either needs to be created or improved. Also that some "bugs" can be fixed with documentation, i.e., telling people what to do or not do. When support engineers are our friends, we do better docs.
— Meta Beth: Finite & Infinite Games 🍁🎗🇺🇦 💙 🐝 (@professorsan) November 11, 2020
If "management" asked for the course, be sure to temper expectations: you can't instantly correct significant spelling & grammar issues, but you can teach audience awareness & better communication. Get buy-in that pair writing & peer editing are good use of staff time.
— Paul Goble (@paulgoble) November 10, 2020
DDCL = Documentation Development Life Cycle
Find out what these support staff do, what problems they have, what issues are they are being asked to address with their technical writing and what problems they have. Use their feedback to create practical examples that make sense to them.
There’s absolutely no point in going in there cold and telling them what you think they need to know. You need to find out what are they are trying to achieve. Find out what they need to know to achieve it. Then ask yourself what they already know and what you need to tell them.
Finally, ask yourself what you know and what you need to find out in order to tell them. Successful technical authoring is 10% telling and informing, and 90% finding out.
I’d include this – Technical documentation is not only about the How. Make sure the writers have crisp and clear contextual information on the What, Why, and if applicable why not.
I would look at minimalism for writing support procedures and separating conceptual information from those.
Maybe teaching less about audience analysis. I assume that they know their audience quite well already. The “free time” you could then invest in writing guidelines etc.
The responses from the delegates were also interesting.
The common issues they mentioned were:
- How much detail to include. Almost every delegate mentioned this.
- Getting started (with writing a topic).
- Feeling more comfortable writing.
- Writing more efficiently.
- Structuring a document.
It was a useful exercise in checking the course would cover the most relevant topics.
What do you think a course like this should cover?