Newsletter of the Society for Technical Communication, San Francisco Chapter
April/May 2009
| Newsletter of the Society for Technical Communication, San Francisco Chapter April/May 2009 |
As technical writers we make decisions every day that affect how clear, well-written, and useable our documents are. If we work for an established company we may be following the company’s existing style guide. Style guides provide consistency with choices such as page layout, font choice, headings, indexing, use of graphics, and document organization.
But if we are asked to create a style guide, as Susan Becker was, how do we decide on writing guidelines? And can we justify these choices if we are challenged?
Susan noted that many of the decisions we make are based on our “practitioner’s lore” or body of knowledge and tradition. Much of this lore is based on our opinions which can be grounded in research or not. We discovered that even in our chapter there are differences of opinion on several topics, one example being whether screen shots should be included in product documentation.
For the most part this “practitioner’s lore” serves us well. However, if we encounter disagreements or if we have to justify our decisions, we need more than opinions. We need to be able to back up our opinions with research. If the idea of researching a topic elicits memories of late night thesis writing and causes you to gnash your teeth and pull at your hair, Susan says to stop right there and listen to her story. Research can be interesting and fun.
Susan did a lot of research when she and Dana Chisnell were writing the “NIST Style Guide for Voting Systems”. NIST is the acronym for the National Institute of Standards and Technology which is part of the Department of Commerce (DOC). The problem was that poll workers were very confused when voting machines first came into use. They had a very hard time following the instructions provided; time was lost and many mistakes were made. The 2002 Help America Vote Act tasked NIST to provide the voting system manufacturers with best practices for writing and testing instructions for poll workers. Susan and Dana were responsible for not only writing the style guide, but also documenting the research behind the guidelines they recommended. Susan loved doing this research and learned so much in the process that now she describes herself as a research evangelist. She showed us how to:
1. Find sources to explore a question
2. Read a research article
3. Apply was we learn on the job
1. Finding sources: Where do we begin? Susan had lots of suggestions and, not surprisingly, many were rooted in the internet. But before you start searching, narrow and refine your question so that you don’t get lost in the information.
She suggests doing a literary review of major trends, looking at previous studies, current research, professional journals, web sites and online resources. Possible sources include:
2. Read and assess the research to see if it is applicable to your question. There are several approaches to research including analytic studies, experimental studies, and theoretical studies. Who were the users, how were the tasks controlled, and were tasks realistic and well designed? You can use the same assessment tools to test your documentation.
3. Apply what you learned on your job.
During this project Susan found research showing that documents that are user-centered are easier to comprehend. She demonstrated how she applied this concept to transform the voter machine documents from confusing system-centered text to simple, user-centered text with clear tasks to follow.
We may not always have time to do extensive research on each writing project, but Susan’s enthusiasm and dramatic examples inspired us to look for what’s beyond our practitioner’s lore.
Susan C. Becker is an Information Developer at IBM. She has worked as an independent contractor and technical communication consultant in San Francisco for over 20 years. Susan co-authored the Style Guide for Voting System Documentation for the National Institute of Standards and Technology (NIST). She is a new STC Associate Fellow, past president of the San Francisco chapter, and a member of the Usability Professionals' Association (UPA). Her online and print documentation have received local STC awards.