Pressure caused by the ever-increasing need for faster, more efficient and more accurate communication is pushing tech writing professionals to reinvent their work. When it comes to versatile writing and international communication, Andrew Owenhas really seen it all. His career as a journalist, sailor and a tech writer (since 2006) has carried him from misty London and Dublin to New York, Sydney, Auckland and Wellington and from large international tech corporations to start-ups. Despite being busy with a new project in Dublin, Andrew arranged time for an interview and shared the following “top tips” about recent trends in the field.
When in comes to localization, tech writing as a profession is international by nature, so national standards do not differ much. The UK however, is a special case due to its large domestic software market. Companies that mainly operate in UK market tend to prefer Cambridge English, while most of the tech writing world uses American English. Some writers can also mistake Oxford English (-ize endings) for American English. “Use American English and pick a dictionary,”recommendedAndrew, who prefers Merriam-Webster’s Collegiate dictionary.
While based in London, Andrew wrote documentation that was translated for the Japanese market, and he advises writers to keep in mind cultural sensitivity, keeping sentences short, avoiding colloquialisms, and having a terminology list and sticking to it.
“I always write for translation. Even if the content is never translated, it makes it more accessible to readers who do not have English as a first language,” Andrew said.
National standards might not vary much, but different industries have different needs and therefore it is hard to define a “one-size-fits-all” solution. Despite this there are still factors to consider when choosing a communication guideline for your organization. The following table summarizes the pros and cons between the two major schools of thought, the AP Stylebookand the Chicago Manual of Style.
The “inverted pyramid”, a journalistic way of organizing content, is often preferred, while the Chicago Manual of Style still seems to be the most commonly adopted guidelines. At the same time, agile development environments where documents need to be pushed out faster are calling for lighter structures and practices. Or as Andrew said, “…agile values working code over docs, users value docs over no docs.”
Andrew didn’t want to cite either of the manuals as the “ultimate bible”, but he did offer the following “rules of thumb” as a general guide for colleagues overseas.
- For software docs, use Microsoft Style as the basis of your style guide and adapt it to your needs.
- Choose a style reference, be it AP or Chicago.
- Create a style document that notes only where your style differs from these reference works.
- Remember that it is only a guide, and use your judgment on when to break the rules.
- If you adhere to the contradictory advice in Strunk & White, seek professional help.
As frustrating as it may sound, there are no simple solutions for multidimensional problems. But the tech writing profession is about to go through some major changes in the near future, and these changes will hopefully create some coherence.
“I think we’re going to abandon ways of working that haven’t changed much in thirty years and all go over to the docs-as-code model where we work in the same repositories as developers, writing in markdown, and doc publication is almost entirely automated,” Andrew said.
We are looking forward to seeing the evolution of the tech writing profession. One thing is for sure, every organization has some improvements to make when it comes to communication practices, and therefore there will always be a need for innovative approaches and great communicators.
