Technical Communication UK 2012

The Technical Communication UK (https://istc.org.uk/tcuk) 2012 conference was in Newcastle, 2-4 October. Mike Unwalla reports on the presentations that he attended.

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:

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/en/web/common-european-framework-reference-languages/home). 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:

To increase the quality of documentation, use tools and methods such as these:

A fish tale: improve your career by watching fish

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:

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.

The term technical writer is a low-value term. Instead, use a name that gives you more money. Some examples are as follows:

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 do not agree that the term technical writer is a low-value term. Some technical writers have small salaries, but some technical writers have large salaries.

Another lesson is to adapt or die. Technical communication is continuously developing. Learn about DITA, XML, controlled English, and personas. Do not waste time learning how to use Word.

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.

Many small companies use freelance technical writers. Those companies want to be able to change the documentation. Unlike Word, DITA and FrameMaker are not useful to these companies.

Why would we want to talk to customers or them to us?

Speakers: Ian Ampleford and Peter Jones, ARM

ARM creates intellectual property and sells licences for that intellectual property to its customers.

Mekon (https://mekon.com) showed that ARM uses unsustainable methods to create documentation. Mekon recommended that ARM speaks to its customers, for 2 reasons:

The documentation team gave an audience analysis and task analysis questionnaire to some customers. To find those customers, the documentation team asked the sales and marketing department.

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:

Customers said, "I have an idea. Help me to make it work." Customers wanted these things:

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:

The evolution of translation tools and its impact on user accessibility

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:

Now, documents in hundreds of file formats are translated. Examples of file formats that can contain content for translation are ASP, HTML, PNG, and JavaScript.

Content for translation comes from many different sources, such as these:

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.

Self-service support starts in the UI

Speaker: Rachel Potts, 3di Information Solutions (https://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:

Do everything that I need (exactly how I want it done)

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:

Wait x seconds

This user interface is better:

Wait x seconds

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.

CPD–why should I bother?

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)".

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:

Internationalization as an accessibility issue

Speakers: Kai Weber (https://kaiweber.wordpress.com/), Karen Mardahl (www.mardahl.dk), Ray Gallon

An EU survey shows that 50% of online users in the EU read in a foreign language

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.

Language is part of accessibility. Simplified English is a good start for translation. Simplified English decreases costs. Therefore, company accountants are happy.

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.

Why structured content is increasingly becoming a necessity, not an option

Speaker: Scott Abel, The Content Wrangler (www.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:

Structured content is an old idea. STOP was before DocBook. New ideas and methods need time before most people use them. Sometimes, 15 or 20 years are necessary before good ideas become popular.

Scott recommends Document Engineering: Analyzing and Designing Documents for Business Informatics and Web Services by Robert J. Glushko and Tim McGrath.

Sustainability and information development

Speaker: Tom Dumic

The word sustainability has 2 primary meanings:

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:

If software developers put information into a wiki, these problems can occur:

To make the method successful, the method must be part of a larger process, and the method must be easy to use. 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:

The method is good, specially for reference documentation. For an example of a related method, see Integrating tutorial help with developer-written reference documentation.

Collaboration and community: lessons from open source projects

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."

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/):

In Why Do People Write Free Documentation? Results of a Survey, Andy Oram showed that people contribute for many reasons.

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:

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:

Letters from the editor

Speaker: David Farbey

In 1976, NASA published The levels of edit (https://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:

The best workflow is as follows:

  1. The technical author and the editor plan the work (policy editing).
  2. The technical author writes the text.
  3. Subject-matter experts review the text.
  4. The technical author corrects the text.
  5. The editor reviews the text (developmental editing).
  6. The technical author corrects the text.
  7. A proofreader copy-edits the text.
  8. The text is published.

David gave this advice about editing:

With structured writing, edit each chunk when it is completed.

Social media and documentation: what could go wrong?

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:

However, social media fails primarily because the software does not fit the organization.

Diego gave these comments about the failure of social media:

RSS feed

© TechScribe, Sheffield, South Yorkshire. Page created 2012-12-18

  1. Search | A to Z
  2. Services
  3. Resources home page
  4. Writing
  5. Business development
  6. ISTC online groups
  7. Reviews: TCUK 2012
  8. Glossary