How do you teach grammar and punctuation to experienced technical professionals without seeming patronising?
To follow that: how do you condense the skills and knowledge needed for technical communication into a single day of training?
A version of this post was originally published in the Spring 2018 issue of Communicator.
At TWi, we work with clients in a range of industries. The engineers, product designers, and developers we work with are smart, experienced people with one thing in common: they need to write documentation. However, many of them have never been taught how to write well. They find it painful and are often unsatisfied with the results.
While our primary service is to take that task off their hands, we realised that we could also help by sharing our expertise through an introductory course in technical writing. In this post, I’ll describe how we designed that course to meet our clients’ needs, and how we’ve improved the course over time.
Avoiding Academia
We knew that most clients recognised the value of this training, but we still wanted to ward off any potential scepticism. We also did not want to delve into the sticky intricacies of language for no reason other than that they exist. Our time was limited, and we could only cover the fundamentals of our craft. To make the best use of everyone’s time (and to avoid retreading old schoolwork), the course material had to be practical and rooted in the daily responsibilities of our participants.
To follow this principle, we looked at the stages of the documentation process (see Figure 1). We then used these stages to roughly direct the modules of the course:
- The Introduction presents the goals of technical writing and provides examples of how documentation can affect an organisation both positively and negatively.
- Information Gathering introduces audience analysis, planning, and research.
- Mechanics of Writing covers common grammar and punctuation mistakes.
- Elements of Structure demonstrates how to structure a document and present information clearly.
- Characteristics of Good Writing describes techniques for writing clearly and concisely.
- Style Guides and Templates demonstrates how to create consistent documents.
- Editing covers self-editing and peer editing.
Figure 1: The Documentation Cycle
Just as the overall structure follows the documentation process, each module consists of several lessons that map to real tasks (for example, making information easy to find). This task-based approach helped us to decide which ideas were most important to include in the course. Within each lesson, all examples are inspired by real technical material, using language from a variety of industries. This link to real tasks reassures participants that we don’t just talk about Oxford commas for fun. (That said, the Oxford comma generally sparks an entertaining debate.)
We’re conscious that there are many ways to create documentation, and we encourage discussion about the differences between our recommendations and an organisation’s existing practice. That discussion often provides the most valuable learning — for both the participants and ourselves.
Putting it into Practice
To keep energy levels up, we include exercises that give participants a chance to test their new skills. Simple exercises, such as correct comma and apostrophe usage, lead into more complicated challenges. By the end of the day, participants will break apart long blocks of text, correct grammar, rewrite for concision and clarity, and perform both high-level edits and copy edits on their own and each other’s texts.
We also include exercises on applying style guidelines, using styles in Microsoft Word, and creating a simple Word template. Often, participants are surprised to learn about simple features, such as styles and spacing options, that will make their lives easier. While we don’t provide comprehensive training on Word, we do provide a foundation for participants to build on.
Improving the Content
Between the early deliveries, the course content changed drastically. Some topics needed more detail. Others were brushed over as irrelevant by participants. Balancing the appropriate amounts of information within the timeframe of the training day is a constant challenge, especially given the needs of different clients. For example, one organisation may ignore templates, while another organisation might want to create their own. Even within an organisation, members of different teams often have different needs.
To address this, we developed an expandable level of detail for many lessons. If a topic is not relevant for a client, we outline it and move on. If the topic is relevant, we discuss it in depth. Even if a topic is not directly relevant, it’s still good to mention how it fits into the documentation process. Though the client doesn’t need it now, they might in the future.
One of the more difficult refinements was adjusting the exercises to be appropriately challenging and to take the correct amount of time. The Microsoft Word exercises, in particular, required multiple tweaks to hit the sweet spot. A recurring issue is the variety of Word versions in use in different organisations; we must have seen every version of Word released in the last twenty years!
Splitting the Handbook
Much of the early feedback was about the participant handbook: one of the documents that accompany the course. Originally, this handbook contained key images from the presentation, space for taking notes, supporting information, and exercises. Participants reported that the supporting information was difficult to find quickly, hidden as it was between images, exercises, and note-taking sections. This reduced its value as something the participants could refer to later, so we moved this information into a separate Job Aids booklet. This standalone booklet is more useful for the participants when they’re back at their desk.
We also heard that the note-taking sections were too restrictive, so we replaced them with the most basic alternative: an A4 pad. (We also took this as a good reminder that sometimes the simplest solution is the best.)
This left the exercises and key images from the slides alone in the participant handbook. We decided to drop the images and convert it entirely to an exercise handbook. This had a hidden benefit: the participants can find exercises much more quickly. Instead of looking for a certain page, they just turn the page from the last exercise. Though it’s a small thing, it makes the classroom experience that little bit smoother.
We’ve received much better feedback since making these changes, especially for the Job Aids booklet: participants have reported that it’s a great consultation tool when they’re unsure of something, and it’s well laid out to quickly answer their questions.
Figure 2: Splitting the Handbook
Getting it Right
Technical communication is a difficult task, and reducing the skills involved to a one-day training course might seem impossible. But our clients appreciate the course, and anything we do to improve their documentation is worth it.
For me, the most interesting aspect of this project is the feedback on what participants find most useful. It’s easy to forget that not everyone knows what we know. I’m always surprised by how the simplest things (from our perspective) can be the most valuable to non-writers. Here are some topics that are flagged regularly as being most valuable:
- The correct use of bulleted and numbered lists
- The use of templates in Word
- The value of line and paragraph spacing
- Techniques for writing concisely, such as the active voice, avoiding redundancy, and standard phrasing
This project is ongoing. We return from each delivery with new ideas. While the changes have settled into minor tweaks, I don’t expect to call this project finished anytime soon. Writing documentation is a cyclical process and there’s always something you can improve — whether you’re an experienced technical communicator, or an engineer grudgingly writing a report.
Images Used
- Image by Kaleidico, licensed by Unsplash
