Teaching geeks to fish: tales of a contagious documentarian.¶
Description
I love my job. My title is "Information Architect", but that’s mostly because "She Who Figures Out What We Need To Do About Our Documentation And Does It" is too wordy for HR. I work in a product unit of about 350 people creating software for developers, very few of them skilled writers or native speakers of English. My role is to figure out how we can produce good documentation.
I have a problem of scale: I can’t do all of the technical writing we need. So instead, I’ve become a contagious documentarian. Over the last year, I’ve infected taught technical writing to over 200 people around my company. My 3 1/2 hour course, "Technical Writing for Techies", is popular, and seems to be effective. There’s been a noticeable improvement in the writing we’re producing, and (even better) an awareness that good writing is an achievable, even enjoyable, thing.
When I describe the course formally, I tend to list attendee objectives such as:
- Think about the audience and how to write for them.
- Study and practice different writing techniques.
- Understand and use a style guide.
- Learn ways to improve word choice and sentence structure.
- Study the commonest mistakes that non‐native speakers make in English and how to correct them. (etc)
And I do cover all of those topics. But just between us, my real objectives for my students are:
- Stay awake.
- Feel welcome and relaxed enough to participate openly.
- Finish the course feeling competent and capable about writing.
- Trust the Information Architect enough to come to her with future problems.
- Want to be part of a community of documentarians.
I’ll talk about the course structure, some of the ways I’ve designed and delivered it to meet both sets of objectives, how it has evolved over time, and what I’ve learned while giving it.
- Conference: Write the Docs Prague
- Year: 2018
