TechWhirl’s coverage of WritersUA 2012 is sponsored by Madcap Software. Find out more and download a trial copy of Flare 8.
WritersUA 2012 started with the basics in the pre-conference sessions on Sunday, March 11. Even with 17 years of experience in technical communications, I found the four content strategy sessions to be very valuable and informative, as a refresher on the basics of any technical communications project, and as applied to user assistance (UA).
Attendees were not required to stay with one of three offered tracks (Content Strategy, Tools and Technologies, or Emerging Skills) to earn the UA101 certification offered at the WritersUA conference, though some did. Still, only a small percentage of conference goers made it to these valuable pre-conference sessions.
The Content Strategy track of UA101 included:
- Writing Procedures by Leah Guren
- Editing by Rhonda Bracey
- Task Analysis by Leah Guren
- SME Interviewing by Nicky Bleiel
Writing Procedures
Leah Guren, owner of Cow TC, first spoke about writing task-based topics in help, and guided attendees in a walkthrough of steps to create effective procedures. She believes users are driven to help because there is something they want to do, not because they care about features. “If we don’t give our users good, clear, task-based information, we’re going to lose them.” She called help “read-to-do” or “cookbook documentation.”
Guren coined the term “jigsaw theory” to explain the importance of providing users with the right information at the right time and in the right sequence; if they can’t view the picture on the puzzle box, or it’s missing some pieces, or has extra pieces from another puzzle, users are hindered getting the puzzle done. She equated the title of a procedure to the cover picture, which must be meaningful to a user and is best if begun with a gerund form of a verb (except for “using” which indicates a feature and not a task). The introduction briefly describes the task covered by the procedure and focuses on facts, prerequisites and hazards.
Actual steps should be in short, direct sentences: not so brief as to be unhelpful, nor so long that steps are missed, nor so inclusive as to confuse the user with multiple options for continuing. Guren referred to this as the chew and swallow method, “chunking steps based on complexity and what makes sense based on your audience.” Using layers of visual cues, such as inline icons and hypertexts to additional information/extended content, and doing so dynamically and consistently provides appropriate content for mixed capability audiences, confirming they are on the right track. Guren provided an example exercise and guided attendees through two others, one on creating a title and intro to a procedure, the other on developing a simple procedure.
Almost to emphasize how important it is to cover these basics, even for experienced technical writers, in the closing Q&A an attendee asked what people have against passive voice, to which Guren responded respectfully, “It’s not that what people have against passive voice; it’s what technical communicators and usability people should have against passive voice—passive voice is harder to understand, significantly…it makes longer sentences, it’s harder to translate…it masks and disguises the responsbility element, who has to do the action…passive voice is one of the worst things that you can do…for writing procedures it’s never better.”
Editing Content for User Assistance
Rhonda Bracey, of CyberText Consulting who has worked for Chevron for several years, stated that in editing you “tidy-up writing.” She packed a ton of information in short time, referencing other sources and the ever changing standards of what is correct, including Scott Nesbitt’s blog on editing. Bracey said, “the role of the editor in user assistance is helping the writer and/or developers by fixing errors and/or suggesting improvements.”
Quoting a tweet from the Adobe Tool Seminar earlier, Bracey said, “An editor’s true value is enhancing and improving the content,” having the user foremost in mind, not the developers or authors.
As with all technical communications, Bracey focused on the three Cs—clarity, consistency and conciseness. An editor of user assistance will check for these, which Bracey gave seven instances of what an editor may identify, referencing writeorrevisedaily.wordpress.com/2012/01/04/add-value-to-gui-design/. She then discussed three basic types of editing: Rules-based (checking against style guides, proofing, typos), Analysis-based (looking at content, substantive editing) and Technical (testing against product).
While she spoke of these editing types as distinct, Bracey also implied that doing all three ensures accurate and adequate help that is also appropriate for the audience. But these cannot be done all at once; issues must be handled in separate passes. While we may already being doing this, Bracey offered several useful tips:
- Suspend existent knowledge of product when editing
- Take multiple passes and only tackle one/a few issues at a time
- Use will instead of shall because shall has a strong legal meaning
- Tighten language by cutting unnecessary words, such as using near or a more specific measurement rather than in close proximity to
- Ensure logic and sequence, active voice, serious consequences and multiple steps in procedures, and emphasize any hefty consequences before action
- Beware of being overly pedantic
- Share style sheets and checklists with your team and apply those lists
- Use style sheets to document decisions that differ from the style guide
Bracey closed with pros and cons and costs of different editing tools. My company uses tools created in Access, which outputs PDFs that are easily saved as RTFs to allow using review tools that already come with Word, but it may be worth trying other add-ins such as StyleWriter, PerfectIt, EditTools and AP StyleGuard.
Task Analysis for Targeted Technical Communications
Guren came back to tie UA to the basic goals of technical communications—being good at humanizing, being personable and ensuring targeted knowledge sharing— by doing an audience/task analysis. According to Guren, audience and task analysis are important to understanding your audience, which in turn supports building personas that mitigate the risk that you as a technical communicator will likely approach instructions and procedures differently than the average user.
Guren suggested starting with simple audience analysis tasks: identifying demographics, language skills, technical background, comfort with online help and use of product. Tap in-house resources such as help-desk personnel who talk to the people that are actually using the product. While the ideal situation would be the “Jane Goodall thing…watch the users in their natural habitat,” user assistance writers can create personas. After doing the research, it’s still hard to describe a real user. “What does someone look like who is 64% male and in that age range? It’s really hard to talk to a person like that.” Create personas to provide a full story, and consider including a photo of someone to help identify with real people and their needs.
As a relevant example, Guren had the attendees identify the users of a website tool obviously created as games for children to understand number concepts. So, while users of the game may be children 3-7 years old, users of the game’s help, your audience, would more likely be teachers, parents and the IT people who maintain the computers being used to play the game. Think about what those users would need to know, what they would do with the product.
When analyzing the tasks to cover in help, Guren encourages user assistance writers to think in terms of the users’ workflows—scenarios and sequences, the frequency of a task, and situations in which/during which the user may need assistance. She had attendees think about what a user would do when buying camera—the first task isn’t using a feature, it’s more likely be turning it on. So in a quick-start guide, identify what most people (users in the middle of a bell curve) would do when they first get a product.
Guren suggested brainstorming with your team on workflow tasks, scenario-based tasks, and troubleshooting tasks. This brainstorming delves into procedures, not features, and participants should feel free to duplicate them during brainstorming to address everything a user might search for. In the example of a cappuccino machine they may froth milk, foam milk, or make hot milk to do the same thing, and wish to clean or wash the machine. Keep in mind the personas while brainstorming why users are looking at help. It wouldn’t be for fun; it would be because they have a problem or don’t know how to do something. After brainstorming, you can then remove duplicate, unnecessary or unwanted tasks.
For the final exercise, Guren had attendees examine a marketing piece outlining the features of a time-keeping system, and then brainstorm to identify workflows or tasks behind these features. I have to say was very daunting and really made me think about what the user needs. “You are acting as the translator between the SMEs and the marketing people who are talking feature, feature, feature, and you have to input all of this stuff and spit out task, task, task, task. The users don’t care about this [pointing to the marketing piece], they know the product does this stuff. They want to know how do I, how do I, so tell me how I do…”
SME Interviewing
Nicky Bleiel of Component One rounded out UA101 Content Strategy with information gathering—finding SMEs, being clear about what will be needed, and then interviewing them. She noted the results a previous WritersUA skills survey that found interviewing was sixth on the list, while a more recent survey shows it as fifth, indicating that more people in technical communications may have begun to recognize its importance.
Bleiel focused on gathering information and preparing before talking to a SME, pointing out that you need to think about who your SMEs are and what you want to ask them in advance. Doing the background work helps narrow exactly who the SMEs are and what they can offer and establishes a level of respect and confidence in your SMEs. SMEs are often customers or developers, but could also be analysts, quality assurance staff, tech support, product managers or sales, all of whom offer a different perspective and information.
The Golden Rule of interviewing SMEs is to be prepared. When scheduling a SME meeting, specify what you need from the SME and include documentation details and clearly defined deadlines in the deliverables plan for the project. Bleiel recommends keeping the process of interviewing SMEs simple, and developing a process (with a designed workflow, templates and guidelines for review) is key, In previous work for buyers, I created a template form in Word that identified the minimum information requirements to add a new product to the company catalog. This helped ensure buyers acquired an adequate amount of details from vendor representatives and approved the description and images as catalog-ready without taking additional time or requiring catalog department staff to contact vendors directly.
Our template helped us avoid interviews and meetings, which was a significant factor. In the same way, as user assistance writers, Bleiel notes that you must address your information needs while respecting your SMEs’ preferences for obtaining information—via email, phone, face-to-face, more informal or formal, more friendly or brusque. Follow general office and interviewing etiquette, such as preparing questions in advance, being prompt, taking notes, agreeing to follow-up plans and saying thank you. She recommends ensuring the appropriateness of the tried and true SME bribe of cookies or brownies, and to do so if you know the individual would appreciate that.
In summary her main point was that to obtain the help you need, you must show adequate respect and appreciation for SME efforts, send formal thank-yous, and share successes or issues with the entire team and management.
Bleiel said to expect to receive various responses to requests for even quick reviews or precise queries, including corrections to grammar spelling, suggestions for formatting/style and copy additions. Don’t be surprised by it, just move forward. She said there is “really no secret to it…just be ready to go,” pointing to a Colin Powell quote, “There are no secrets to success. It is the result of preparation, hard work, and learning from failure.”
She concluded her presentation with an extensive list of resources, including:
- A three-part blog entry of hers on managing Word document reviews in MS SharePoint at our.componentone.com
- Nuts and Bolts: Working with Subject Matter Experts from the online Learning Solutions Magazine
- How to Get the most out of Your Subject Matter Experts from the Rapid E-Learning Blog
- Subject Matter Expert: 5 Tips for Working with a SME by eLearnerEngaged
- Interviewing SMEs from WritersUA
- Conducting Successful SME Interviews from the STC Usability SIG newsletter
- Technical Writing 101 by Alan Pringle and Sarah O’Keefe
