The technical communication culture: a review

The ISTC conference was in Liverpool, UK, 2-4 October 2007. Mike Unwalla reports on the presentations that he attended.

Keynote address

Scott Abel (www.thecontentwrangler.com) ruffled a few feathers in the keynote address. Some technical communicators seem to spend too much time agonising about the details of grammar. Of course, it is important, but it is only a low-level detail. We need to focus on the skills that businesses need to add value to their products and services. Each technical communication company needs to know its own unique selling point and the differences between other technical communication businesses. I agree fully with Scott.

Users' expectations are changing faster than the technical communication world. Web 2.0 leverages the Internet as an operating system to help people 'do stuff'. A few days before I heard Scott speak, I added 'Alternatives to software documentation' to the TechScribe website. Scott showed how much I had not considered.

Scott enthused about some of the many new tools that are available. For example, tagging is a type of bookmarking. People tag content (typically, HTML files that they find on the Internet) with words and phrases. Unlike a taxonomy, this 'folksonomy' can contain any tags that a person finds useful. People can share their tags on websites such as Delicious.

Another example is Yahoo! Pipes (https://en.wikipedia.org/wiki/Yahoo!_Pipes). When I returned to the office, I looked at this. The introductory video shows how to create a mashup from different data sources. In some ways, it is similar to a visual editor for a relational database: you grab an object, apply some filters to specify the data that you want (or do not want) and then pipe the resulting data to some other object. Therefore, it is an old concept that is being used in a new and exciting manner.

I have my doubts about user-generated content. In the worst case, the result can be a ragbag of questions and answers that have no structure. We have all seen newsgroups where over time, the same questions are asked many times. I asked Scott about this, and I am happy to report that he does not agree that all the new forms of content generation are a good thing from a technical communication perspective. However, all options are worth considering.

Certification for technical authors

Tekom (www.tekom.de), the German society for technical communicators, started a certification programme in 2003. Michael Fritz and Daniela Straub summarized the certification programme.

Why was certification introduced? Although university degrees have been available since 1990, good candidates for the technical communication industry are in demand. The law does not regulate education for technical communicators, and there is a lack of standards. Fifteen academic institutions have technical writing programmes. The universities do not see the Tekom programme as a threat—it is complementary to their courses.

Tekom qualification has three major steps:

The total cost of the programme is approximately 7000 euros, and to date, 124 candidates have passed the examination.

Translation-oriented authoring—a prerequisite for efficient authoring

Expenditure each year for writing and translating technical documentation is estimated to be 9,000,000,000 euros in Germany, according to the conference information given by Across Systems (www.across.net). The trend is upwards. Urs Huechting showed how to minimize the cost of translation.

"The only sustainable advantage a firm has comes from what it collectively knows, how efficiently it uses what it knows, and how readily it acquires and uses new knowledge" (Nagar Lai, 2006). Companies need to identify knowledge, and then use a tool to capture knowledge. Sometimes, obstacles to the sharing of knowledge are because of people, not technology. Possibly, it is too difficult, people have their own preferred processes, or a silo mentality exists between departments.

Possible solutions include project management, workflow management, quality management, translation memory systems, terminology databases, and real-time authoring assistance.

Ideally, support for translation starts when a technical author writes a source document. One problem is deciding how to formulate a sentence. Usually, many different variations are possible. When many technical authors collaborate on one document, the problem can become worse.

Inconsistent source text leads to higher costs of translation, support, and quality assurance. A small example showed how controlling vocabulary and structure means that only three words need to be translated. The uncontrolled text contained 20 words (at any one time only three or four words need to be translated, but over the entire document, each variation of a phrase needs to be translated). Because all translations are likely to use translation memory systems, the cost saving is large.

Furthermore, inconsistent technical terms in technical documentation can lead to confused customers. For example, what is the difference between 'hard disk' and 'hard drive'? Consistent use of recommended terms leads to clearer documentation, and therefore, to increased customer satisfaction.

Managing the lifecycle of your technical communication

One traditional technical author was very unhappy because he thought that he was only a cog in a machine. He "felt like a robot" according to Michael Ingledew (https://techdataworld.com/web/). The traditional method is that content is authored. The new reality is that content is manufactured (TechScribe agrees with that idea).

The business drivers include shortened document life cycles (because of shortened product life cycles), growing complexity of products, and decreased budgets.

Documents are compiled, transformed, and fragmented during the manufacturing process. A technical publications department needs a system to manage and control the process of documentation manufacture. An essential element of the system is the ability to create portions of a document in any sequence (I am not convinced that is so different from a traditional authoring environment—the content can be created in any sequence).

A challenge is that we need ways to manage the content. Each fragment of content needs to be assigned to a technical author, tracked, go through quality control, and have metrics extracted from it. Ideally, there is integration with translation systems and project management systems.

To close, Michael showed that the Horizon product was a comprehensive solution to the problems about which he spoke. The Horizon Dashboard serves as a content command centre, and it lets managers specify and control the documentation process.

Leveraging DITA in a multilingual environment

John Hodgson explained that in single-source publishing, DITA helps to make sure that topics are re-used. For globalization, using DITA means that only the content needs to be translated, it is easy to change the content, and quantity of translation can be decreased (because only text that is different from previous translations needs to be translated).

Workflow in the development process is complex. Topics must be created by technical authors, verified by editors, assigned to translators, and approved for release. Idiom WorldServer™ works alongside content management systems to automate the entire workflow.

Writing justifications and comparative analyses

In contrast to the climactic method of writing in which authors "make them laugh, make them cry, but make them wait", in business, we use a pyramid structure to write reports. The basic report structure is summary, background (introduction), investigation, results (conclusions or recommendations), and evidence.

Ron Blicq's (www.rgilearning.com) fascinating exposition showed how to write a comparative analysis (also known as a justification) in two ways: objective and subjective.

At first sight, it seems strange to write a subjective report—surely all reports are objective? Ron gave two examples to clarify the situation.

If a customer says, "you are the expert, tell us what you think," write a subjective report. After the summary and introduction, give the criteria for selection and prove them. Then, for each subject that you are evaluating, discuss the features and 'sell' them. Finally, draw conclusions and make recommendations.

If a customer says, "we think that option X is best, but prepare a report and let us know," write an objective report. After the summary and introduction, describe each subject. Discuss facts only, and tell the reader about the product or service. Sequence the subjects from best to worst or from worst to best, but do not tell the reader the sequence. Specify the selection criteria. Then compare each subject against the criteria (do not compare the subjects against one another). Finally, draw conclusions and make recommendations.

When a customer has a preference, and your investigations show that an alternative solution is better, you must be diplomatic. In the summary, do not write, "we recommend Y". Instead, write, "although <customer> prefers X, our report shows that other options may be suitable and need to be considered."

Editor's note. The winter 2007 issue of Communicator (https://istc.org.uk/homepage/publications-and-resources/communicator/) will have an article by Ron that is about with how to write justifications.

Developing a communication-across-the-curriculum culture

Sometimes, university students in technical fields are bad at communication. The Faculty of Engineering at the University of the West Indies (UWI) had a large problem, and the local business community expressed concern about the low communication skills that some graduates possessed. Halcyon Lawrence has the job of assisting students, and she explained the processes, problems, and possibilities for interventions to assist students.

What is a communication-across-the-curriculum (CAC) culture? It seeks to make significant communications-based interventions in the curriculum. It includes things such as team building, technical writing skills, and presentation skills, for example.

The first step is to identify the institutional and stakeholder goals. Acknowledging and addressing 'turf' issues is important. Halcyon developed a PR plan, which included promoting the programme at many levels. One challenge is that the term 'technical communicator' is not known at the Faculty of Engineering.

A CAC culture exists when, amongst other things, the interventions are not obvious, but are blended with the content of an academic course.

A case study from the department of Electrical and Computer Engineering showed the benefits of a CAC culture. The department takes in approximately 75 undergraduate students a year, who engage on a 3-year programme. Intervention is at three levels:

Students hated the programme in the first year. They tolerated it in the second year. After graduation, they really appreciated the programme.

Strengths of the CAC programme included external validation of the programme through accreditation bodies, and support from the Dean, the Head of Department, and the library personnel.

The educational system creates a critical distinction between disciplines, and a strong tendency to stream students exists. Other weaknesses include overloaded resources, students' resistance, little support from lecturers, and no CAC culture.

Success has been measured by the large improvement in the standard of research projects.

Staying agile

Subtitled, "Published documentation in rapid application development environments," David Nixon's presentation was a lively discussion of agile software development and its effect on documentation and documenters.

The characteristics of agile software development include small project teams, zealous leadership, solutions that are just good enough, frequent changes, scope creep, and fast delivery of incremental solutions.

Aids to survival for the documenter include:

Question time was interesting! Some people thought that 'agile' was an amateur's method of creating software: "it's three guys working out of a shed." That is possibly a harsh judgement in the light of the agile manifesto (https://agilemanifesto.org).

Reasons to be cheerful—part 1

Despite the changes in our industry, technical authors have good reasons to be cheerful, said Paul Ballard (https://3di-info.com). (A show of hands indicated that most people in the presentation were technical authors.)

What is a technical author good for?

The basic methods of technical authoring will stay the same, although tools will change. For example, modular writing is a good thing, whether or not we use a CMS to store the content.

Products are becoming increasingly complex, regulation is increasing, and product life cycles are becoming shorter. Companies are likely to need technical communicators to manage these issues.

However, we have problems to solve. For example, bad technical authors exist (and they give the profession a bad reputation), and only limited professional recognition is available.

CMS: how to avoid a content mess system

A document reflects a customer's perspective, said Sacha Fedier. It is the finished product. Companies pay little or no attention to the management of information that the product contains, and few companies understand the product information life cycle of documentation.

With a standard content management system (CMS), it is possible to store conflicting information. Additionally, each saved change leads to a new version, so an explosion of versions and documents occurs.

To prevent these problems, use the methods of information management, for example:

The information engineering process results in:

This results in an information model that can be defined by an information type definition.

An information model defines the structure of a document. Content is semantically tagged. A simple example is:

<work step>
   <instruction>
       instructional text here…
   </instruction>
       :
</work step>

Module size affect complexity and redundancy Management of information can be a problem. A trade-off exists between complexity and redundancy, as shown in the graphic. As the size of content decreases, the management complexity increases. However, as the size increases, redundancy also increases.

In a case study, Sacha explained that Daimler decreased the maintenance burden of documentation by approximately 35 times (not per cent!) by using information management tools and techniques. The demonstration was enlightening: an interactive technical manual had links to a shopping basket, so that support engineers can buy spare parts easily.

Around the World in 80ms

Sometimes, teams are scattered across the globe, and this raises challenges for business process management (BPM), explained Holger Rath (www.empolis.com). People are in different time zones and possibly have different desktop applications. Processes are not identical in different locations.

BPM can be improved by integrating a content management system (CMS) with workflow management.

CMS does not work in isolation. Data flows (content, status, metadata, and user information) between BPM tools and CMS tools are bi-directional. A question occurs, "is BPM embedded in CMS, or is CMS embedded in BPM?" As one may expect, it depends on the situation.

Five golden rules of BPM are:

Summary

The ISTC conference gave a fascinating insight into the technical communication industry. From the conference programme, too many vendors were presenting for my taste. However, I was pleasantly surprised by the vendor presentations that I saw, because they focused on the concepts behind the tools, instead of on tools themselves.

RSS feed

© TechScribe, Sheffield, South Yorkshire. Page created 2007-10-15

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