Quality across borders: practical measures to ensure best-value documentation in global technology businesses
Speakers: Rowan Shaw and Veronica Broughton-Shaw, IV Solutions (www.ivsolutions.co.uk)
Rowan says that good documentation has these properties:
- Grammatically correct.
IV Solutions recruits technical writers in China, India, and other countries where English is not the first language. To make sure that the technical writers are sufficiently good, IV Solutions uses the Common European Framework of Reference for Languages to evaluate technical writers (www.coe.int/t/dg4/education/elp/elp-reg/cefr_EN.asp). The selection process includes an online test, an interview, and a written test.
To help readers who do not have English as a first language, remove problems for the reader. Two good books that explain how to remove problems are as follows:
- The Elements of International English Style, Edmond H Weiss
- The Global English Style Guide, John R Kohl.
To increase the quality of documentation, use tools and methods such as these:
- Style guides.
- Spelling checkers, readability checkers, and term checkers. Examples of such software are StyleWriter and Acrolinx IQ. (Later in the conference, I announced the release of the TechScribe open-source term checker for ASD-STE100.)
- Copy editing.
- Testing by the audience and by subject-matter experts.
Speaker: Leah Guren, Cow TC (www.cowtc.com)
Leah's father used fishing as a metaphor for life. For example, he frequently used idioms such as these:
- "The big one gets away."
- "You need to use a different lure."
To help technical communicators to improve their careers, Leah gave 6 lessons that used fish-based metaphors.
One lesson is to invest in better public relations. "A dove is just a pigeon with better PR." Names are important. The common carp and the ornamental koi are the same species of fish. People pay many thousands of pounds for ornamental koi, but they do not pay much money for a common carp.
- Content specialist
- Documentation specialist
- Information architect
- Technical communicator
- User experience facilitator.
I do not agree with Leah. On the TechScribe website, I use the term technical writer because most of my customers use the term technical writer. If I use the term documentation specialist, then the TechScribe website will not appear in the search results for technical writer.
I partly agree. New tools and new methods are important. However, learning to use Word is not a waste of time. Many of the problems with Word that technical writers complain about are caused because the technical writers do not know how to use Word correctly.
Speakers: Ian Ampleford and Peter Jones, ARM
ARM creates intellectual property and sells licences for that intellectual property to its customers.
Mekon (www.mekon.com) showed that ARM uses unsustainable methods to create documentation. Mekon recommended that ARM speaks to its customers, for 2 reasons:
- The customers are involved with the changes to the documentation.
- The quality of the content will increase.
Customers are in many different countries. Local knowledge is important. Sales people can speak to customers. Customers ask questions in their language.
The documentation team learnt many things:
- Sometimes, the documentation is not clear.
- Sometimes, the documentation is not easy to find.
- Information is in many locations.
- Too much information is available.
Customers said, "I have an idea. Help me to make it work." Customers wanted these things:
- More graphics
- Documents that are all in one location
- Content that is easy to find
- Content that is applicable.
The documentation team found that customers did not like documents in HTML format. The method of access was difficult, because to find information, a reader must access hundreds of gigabytes of documentation.
Now, the documentation team does these things to make the documentation better:
- Sends customers updates about processes and problems.
- Uses customer surveys to measure satisfaction. ARM speaks to customers who are not satisfied.
- If there is an error in the documentation, quickly and automatically creates a support case.
- Works with other parts of the business to standardize the deliverables.
Speaker: Tom Gannon, Welocalize (www.welocalize.com)
In 1992, the first version of Trados became available.
Later, translation memory systems helped to automate the translation workflow. Automation decreased human error. Typically, a translation memory system cost £250,000.
In approximately 2003, online translation became available.
In 2005 and 2006, many mergers and acquisitions occurred. For example, in 2005, SDL bought Trados. In 2006, SDL bought IDIOM.
In 2007, after all the mergers and acquisitions, 15 vendors remained. The total market for localization tools is less than $100 million. Some people say that fewer translation tools are necessary.
In 2009, 'on-demand' translation started. On-demand translation has these features:
- Smaller units of work
- More frequent delivery of translation
- Customers want quotes quickly
- Delivery time is short
- Performance is tracked.
Content for translation comes from many different sources, such as these:
- Technical writers
- Translation memory
- User groups
Translation schedules continuously become smaller, but the quality requirements stay high.
In the future, machine translation and open-source software will be used more. More translators will work from home. Only a connection to the Internet is necessary.
Speaker: Rachel Potts, 3di Information Solutions (www.3di-info.com)
Software companies use support portals to help customers to find answers to problems.
Support portals are good, but frequently, the interface on software is bad. Help messages do not give help. Text on error messages is not clear.
Rachel showed the perfect user interface:
The perfect user interface is not possible. However, use the guidelines that follow to make a user interface as good as possible.
To improve error messages, put all the necessary information into an error message. Possibly, have a link to a help topic. In one project, when text on error messages was made clear, questions to the service desk decreased by approximately 45%.
Put necessary information into the user interface. Words on the user interface help users to understand. For example, this user interface gives no help to users:
This user interface is better:
Decrease the 'gap' between the question and the answer. When users press a help button, show links to all the applicable help topics. In drop-down menus, have links to frequent questions.
Speaker: Alison Peck, Clearly Stated (www.clearly-stated.co.uk)
CPD (continuing professional development) is the method by which professional people make sure that their knowledge and skills stay current.
The ISTC does not have a CPD policy. However, members of the ISTC must "maintain and develop skills to facilitate a high degree of ethical competence (that is, the responsible application of skills augmented by the sourcing of professional advice or assistance when the limit of those skills is reached)" (www.istc.org.uk/wp-content/uploads/2011/08/ISTCCodeofProfessionalPractice.pdf).
Employers, professional people, and professional organizations specify what is valid CPD. Context is important. Training that is not related to an employee's work is not CPD. For example, for most members of ISTC, a cookery course is not CPD. However, if you edit cookbooks, a cookery course is probably CPD.
CPD helps the reputation of a profession. However, the measurement of CPD can be difficult. One method of measurement is to count the number of hours of training. Another method is peer validation.
CPD has many benefits, for example:
- Employers have effective employees.
- Customers have better documentation.
- Technical communicators have better job opportunities.
An EU survey shows that 50% of online users in the EU read in a foreign language (http://ec.europa.eu/public_opinion/flash/fl_313_sum_en.pdf).
In a medical procedure, patients received too much radiation. Some patients died. Two primary causes of the accident were as follows:
Methods such as internationalization and global English are not sufficient. First, a document must be internationalized. Then, the document must be localized.
Localization is applicable to graphic and to symbols, not only to text. At TCUK 2011, Patrick Hofmann explained how to create icons for a global audience. However, each reader wants a different symbol.
An interesting book is The Geography of Thought: How Asians and Westerners Think Differently... and Why by Richard E. Nisbett.
Speaker: Scott Abel, The Content Wrangler (http://thecontentwrangler.com)
Structure is important for most things. Google Gravity shows why structure is necessary in a document.
Structured content is necessary for these reasons:
- Specify the content model. Give guidelines to technical writers. Make sure that both people and machines can read a document.
- Increase the usability of content. Give visual indications to readers. Make the document predictable, accessible, and easy to scan.
- Automate the delivery of the document. Transactional content such as order processing on a website requires structure. Location-aware software automatically adapts according to a customer's location.
- Publish a document to many channels efficiently. Use single-sourcing, and remove waste.
- Deliver content in real-time with a content management system. Examples of real-time content are stock trading, emergency information, and customer service information.
- Do more than create content for personas. Supply the right information to the right people at the right time in the right language in the right format.
- Make the content easy to reuse. Mix content in new ways.
Scott recommends Document Engineering: Analyzing and Designing Documents for Business Informatics and Web Services by Robert J. Glushko and Tim McGrath.
Speaker: Tom Dumic
The word sustainability has 2 primary meanings:
- Something can be maintained at a particular level or rate.
- Something can be upheld or to defended.
Typically, sustainability is related to economics, the physical environment, and social equity.
Tom asks, "Is there such a thing as sustainable communication?"
Some limits to sustainable documentation are as follows:
- Development and maintenance is expensive.
- Software developers like to write code, not documentation.
- Technical writers collect information and structure that information. Collecting information is expensive. Sometimes, technical writers do not get complete information.
If software developers put information into a wiki, these problems can occur:
- Wikis become untidy.
- Information is repeated.
- The structure is not clear.
- Software developers do not know where to put information.
To make the method successful, the method must be part of a larger process, and the method must be convenient. Tom gave a sustainable method for documentation.
First, software developers capture information. Then, the software developers put the information into a wiki that is attached to their development environment. Possible wikis are Confluence and DocuWiki. To prevent problems, structure the wiki. For example, use a form to ask about each type of content. Put the content of the form into a structured document.
The method is sustainable:
- Economics. The method does not have the cost of technical writers who investigate each case. The technical writers design the structure initially. Then, the technical writers edit the content.
- Environment. Software developers have an easy tool to use. The software developers do not think about the structure of the document or the format of the text.
- Social equity. All users know the information structure. All users know where to find information. Each user knows what to supply. Teams share knowledge.
The method is good, specially for reference documentation. For an example of a related method, see Integrating tutorial help with developer-written reference documentation.
Speaker: Janet Swisher
In 2004, Janet started to work with documentation for open source software.
Crowd-sourcing is a method in which many people do small tasks. Community-generated content is not the same as crowd-sourcing. Matt Thompson says, "Crowds aren't smart. Communities of peers are."" (https://groups.google.com/forum/#!topic/contentstrategy/0iPphiXSMio).
Managed community-generated content has this structure. An organization can emphasize a particular level.
Communities are not launched. Communities are grown.
In Participation inequality: encouraging more users to contribute, Jakob Nielsen showed that members of a community supply different inputs (www.nngroup.com/articles/participation-inequality/):
- 90% of members in a community are 'lurkers'.
- 9% of members in a community do a small amount of work.
- 1% of members in a community do much work.
In Why Do People Write Free Documentation? Results of a Survey, Andy Oram showed that people contribute for many reasons (http://onlamp.com/pub/a/onlamp/2007/06/14/why-do-people-write-free-documentation-results-of-a-survey.html?page=1).
The accuracy of user-generated content can be a problem. Deciding who sees content, who adds content, and who approves content can be a problem.
Janet gave 2 models for a review process:
- Patch model: submit → review → publish.
Content is public after the review.
- Wiki model: submit → publish → review.
Content is public after it is published and before it is reviewed. Optionally, identify content that is not reviewed.
Sometimes, user-generated content is old and badly organized. Sometimes, user-generated content contains bad grammar and spam.
To prevent these problems, do these things:
- Use good, easy-to-use guidelines and templates.
- Review the content carefully.
- Make sure that the user community has constant participation.
- Be patient.
Speaker: David Farbey
In 1976, NASA published The levels of edit (http://ntrs.nasa.gov/search.jsp?R=19760015018).
The levels of edit identified 9 types of edit and 5 levels of edit.
That level of detail is not necessary. David gave 3 types of edit that are important:
- Policy editing. Policy editing makes sure that the document is necessary. If the document is necessary, policy editing makes sure that the document is the correct type of document.
- Copy editing. Copy editing makes sure that the spelling, formatting, and mechanical style are correct.
- Developmental editing. Developmental editing is the most important type of editing. Developmental editing includes language editing and substantive editing.
The best workflow is as follows:
- The technical author and the editor plan the work (policy editing).
- The technical author writes the text.
- Subject-matter experts review the text.
- The technical author corrects the text.
- The editor reviews the text (developmental editing).
- The technical author corrects the text.
- A proofreader copy-edits the text.
- The text is published.
David gave this advice about editing:
- Editing is not fact checking. Technical authors and subject-matter experts make sure that the facts are correct.
- Editing is not evaluation. The editor does not grade the content.
- The editor's job is to prepare the content for publication (mentoring, not managing).
- Write a style guide for your project. For example, Chicago manual of style is not designed for user guides. Therefore, a project-specific style guide specifies things that are not in Chicago manual of style.
With structured writing, edit each chunk when it is completed.
Speaker: Diego Schiavon
Social media can decrease the cost of transactions and can make an organization more efficient. However, social media can fail. Failure is externally observed. Failure gives problems to people.
Social media fails for many reasons:
- A document has too much information or not sufficient information.
- The content is not maintained.
- Most people do not contribute to the documentation.
- Some people in an organization resist the use of social media or think that social media is a waste of time.
- Managers feel threatened by 'empowered' employees.
- Trolls, spammers, and competitors add incorrect or unwanted information.
- Legal problems.
However, social media fails primarily because the software does not fit the organization.
Diego gave these comments about the failure of social media:
- To help to prevent failure, read about community management.
- Although social media frequently fails, the cost of failure is low.
- 'Build it and they will come' is not true.
- Communities must grow with time and must be nurtured.