The latest style for tech comm: adding value
Over the weekend, a friend showed me an episode of a reality show that featured some commentary by a “style expert.” This expert offered his advice while dressed in an outfit that would work well as a costume in a production of Oliver Twist (and that’s being charitable).
I thought he looked ridiculous and even said to my friend, “Why is it that the people in the style industry can’t seem to dress themselves?” Sometimes, I feel like I’m looking at clothing designed by people on another planet when I see articles and videos about the latest styles.
This morning, I’ve been in much more familiar territory while reading two online conversations about a different kind of style: the application of style guides in technical communication. Scott Abel, Larry Kunz, Julio Vazquez, and others are having an excellent discussion about the purpose and value of style guides, and a posting on Technical Writing World asks about the best reference books for new technical writers.
So, what do style guides do in technical communication? I’m not going to rehash all the excellent points made by Scott, Larry, Julio, and others, but I will say this: I can get really persnickety about inconsistent terminology and other writing issues that style guides address. That concern about quality writing, however, is likely not shared by unhappy end users who are reading knowledge base articles, online help, or manuals to get help with annoying problems. Do you think those end users are looking for beautiful, pristine prose, or the answers to their questions? It’s the latter, I’m afraid, and it’s really painful for The Writer in me to admit that.
Can well-written content make it easier for people to comprehend an explanation of a problem? Absolutely. However, now that forums, blogs, and other social media outlets let everyone provide helpful tips on how to use technology, “decent” and “understandable” writing is often enough.
Those of us in technical communication now need to think about the business cases for style guides, and that means quantifying how the use of style guides affects effort and costs. How much money will consistent terminology and phrasing save on localization costs? Is there suitable software that can help enforce style at the time of content development, and if so, how much does that tool cost vs. the amount of effort it will save on downstream editing? These kinds of questions are tough to answer, and the answers will vary from organization to organization. Contributing to business case evaluations will make you more valuable to your employer. Therefore, I think it’s essential that technical communicators have the ability to address how the tools and processes (including style guides) we use help our employers’ bottom lines.
That sort of business-based thinking leads to the second style-centric conversation: what books should new technical writers read? Several people in that discussion (and other similar discussions I’ve seen lately) suggest style guides, such as The Chicago Manual of Style and the AP Stylebook. I’m very familiar with both books and appreciate their contributions to excellent writing, but I think we may be doing new technical writers a large disservice by recommending style guides as must-reads.
Instead, I think new technical communicators should focus on reading books about the processes and tools behind technical content: single sourcing, structured authoring, localization, the DITA standard, and so on. Writing ability is still very important: as someone who now makes hiring decisions, I consider it to be a prerequisite. However, I will look much more favorably on a candidate who can give me a basic explanation of structured authoring and its benefits over someone who can’t. Showing an understanding of how a process can reduce costs will likely give a job seeker an edge over other applicants.
Writing ability on its own just isn’t enough today in tech comm—these days, employers need (and expect) more:
About the author
Larry Kunz
Thanks, Alan. You’ve done a nice job of focusing the debate.
Consistent terminology and phrasing will save on localization costs, as you said. They also enhance the value of the documentation because they bring out the clarity and lack of ambiguity that readers want. However, it’s much harder to quantify this enhanced value, and we as a profession have hurt ourselves by never figuring out how to do it.
The next question, as you said, is whether it’s more cost-effective to use tools or human editors (or maybe some combination of the two). Scott is saying that choosing the tools is a no-brainer. I’m saying that I’m not so sure — although I can see that the tools are pretty good and getting better. Yes, it’s hard for the writer in me to admit that.
Alan Pringle
Larry,
Automated editing tools don’t have to do as good a job as human editors. Doing *almost* as well may be enough to convince a company to switch. Doesn’t make me happy, but lots of things about reality don’t exactly please me these days.
BTW, thanks for starting the conversation on this topic.
Ruth
Larry:
If you had ever documented a product in a Windows environment that had its own “user accounts” (legacy terminology, even though they are not merely login accounts), where that product required the administrator to create AD “user accounts” for all Windows “user accounts” before creating single-sign-on “user accounts” that would be equivalent to the product “user accounts” as long as the person logging in has a product “user account” on the server created by an administrator with a administrator “user account,” then you would quickly realize that having some ground rules about style and terminology established up front can be critical to alleviating confusion. (Perhaps not all of these accounts should be called “user accounst”!)
I think you are mixing apples and oranges: Knowing how to write and how to identify issues with terminology is a fundamental skill that is tough to acquire on short notice if you don’t have it. Knowing how to use tools, on the other hand, although important, is a skill you can acquire quickly as long as you are not technophobic and are willing to make the effort. I’m tired of people who think that knowing DITA or Flare or FrameMaker or HTML will carry them when they can’t perform audience analysis or figure out how to organize information and write it clearly, concisely, and quickly (yes, there is rarely a copious amount of time to get the job done).
To achieve reasonably consistent doc and still function cost effectively, the documentation organization should have a very short (max 10 or 12 pages) and concise style guide that every writer is required to read up front, internalize, and adhere to when developing docs. (The Chicago Manual of Style is too long and too generic for this purpose.) The new writer will have to adjust to any house style guidelines that are house-specific, so for the first release or two a peer could edit that writer’s work for adherence to the style guide. By then, the professional writer should have internalized the house style, so that a quick read-through of any work might only occasionally find a style error, reducing the need for editing cycles (as there is little time for them anyway).
As for editing tools, I doubt they can fix terminology questions that involve understanding subtle differences in meaning or deal with product-specific usage. So, we all need to get to work on our brief house style guides and, because the world is a changing place, develop a process for revising them as required.