Technical communication, past, present and future: a review

The ISTC (https://istc.org.uk) conference was in Nottingham, UK, 23-25 September 2008. Mike Unwalla reports on the presentations that he attended.

Controlled language: how to write clear documentation for a global market

The announcement was, "Clear the runway." All the vehicles moved off the runway, except the snowplough. The driver thought that he had to remove snow from the runway. In his pre-conference workshop, Berry Braster from Tedopres explained the advantages of controlled language.

Some risks of not controlling language are:

One of the people in the workshop said that some technical writers 'go native' to be part of the engineering team. They write for the engineers, instead of for the audience.

To apply controlled language authoring:

  1. Create a dictionary. Tedopres does a language analysis and a statistical analysis. In the dictionary, there are usually between approximately 2,000 and 3,000 approved terms.
  2. Train the technical writers.
  3. Make sure that the documents are correct. Tedopres has a tool named HyperSTE.

At SAAB, Tedopres trained technical writers to use a controlled language. Some (new) technical writers accepted the methods, but many 'old-school' technical writers showed resistance. Berry says, "With technical writing, you don't want to win the Pulitzer Prize." I agree with that statement, and my presentation on Thursday was about how to control vocabulary.

Keynote address: user assistance cycles

Matthew Ellison (www.ellisonconsulting.com) spoke about cycles in documentation.

Before computers became usual, a technical writer wrote words on a page using a pen. A typist created a typewritten copy, which was sent to a typesetter. The technical writer did not know the appearance of the final published text. Then, word processing tools such as WordStar appeared. A technical writer marked up text with codes that specified the appearance of text, but the technical writer saw only plain text. Next, desktop publishing arrived. WYSIWYG publishing let technical writers see the final appearance of the documents that they created. However, in the past few years, we have seen an increase in the use of XML. Again, technical writers are concerned with only the content, not the final appearance on a printed page or on a screen.

Online help formats changed with time, but some of the newest designs use methods that were popular, and then became unpopular. For example, Windows 3.1 had one help pane that contained the help content. Then Compiled HTML Help came with a tri-pane interface (Contents/Search/Index). Matthew told us that the help in Windows Vista does not have a tri-pane interface. We are back where we started.

Matthew told us about Conrad Gottfredson's 'five moments of need' (https://performancesupport.blogspot.com/2008/01/invitation-to-our-performance-support.html), which are the times when people need help:

  1. When learning for the first time
  2. When learning more
  3. When remembering or applying what has been learnt
  4. When things go wrong
  5. When things change.

Customer-centric technical documentation

Koen Lourdon from Trisoft says that customer-centred documentation has these properties:

With customer-centred documentation, it is possible to use documentation components in many products. Components are translated one time only. Time to market is decreased, because components are translated when they are complete, instead of when all the document is complete.

Trisoft uses conditional text, and the conditions are sometimes complex. Different types of condition exist, for example:

Trisoft CMS is a content management solution for technical communication. To manage conditions, Trisoft CMS has an integrated condition builder, which tests the conditions when a document is checked in to the CMS.

Difficult topics and passive verbs: anyone can write a manual, can't they?

The authors at Alliance and Leicester are amateurs, not professional technical authors. Audrey Philbrooks explained the challenges that her team had when they worked with the amateur authors.

Alliance and Leicester is a financial organization with approximately 250 branches. Two-thirds of the employees work with customers. The industry is highly regulated.

In 2000, a corporate intranet was set up by consultants. Initially, the corporate communications team managed the intranet, but now the business support services team manages it. The intranet has a distributed publishing model, and content strategies are developed, approved, and published by business units.

Four people on the intranet team focus on policy, governance, usability, accessibility, and application development.

When Audrey became responsible for the intranet, some of the content was very bad quality.

Some of the problems were:

Web pages had bad structure, and had these problems:

Many of the authors had the perspective that, "if it is easy to say, it is easy to do. Any fool can write a document." Authors thought that their topics were special and the users were different from others in the organization.

To solve these problems, Information Mapping consultants created new web pages. That decreased the content by 50%.

Authors were trained in basic English grammar, so that they can create suitable content.

To help authors, standards and guidelines for were established for both content and usability.

Audrey said, "It's a journey, not a destination." The team had failures along the journey. The primary mistake from authors was that they thought they knew it all. They were writing to show off what they knew, not what helped readers. They were writing to please their managers, not the readers.

Remote management of technical authors in China and India for Motorola Networks

Does the outsourcing of documentation have a bad result on the quality of documentation? Peter Newsom worked at Motorola Networks until July 2008, and his case study explained the problems and successes that the documentation team had.

Technical documentation contractors in the UK had replaced approximately 15 permanent technical authors. A small team of permanent technical authors remained. The technical authors were changing approximately 70 technical books to XML using Epic Editor (now Arbortext Editor).

To decrease costs, management decided to outsource documentation, and Peter (with the documentation team) had to apply the management strategy.

Immediate tasks that followed were:

The quality of some of the documentation from the new technical authors was low. For example, one document contained the text, "If a chip overheats, there is danger of flatulence." Therefore, the new technical authors attended a training course in technical authoring.

The actions were not sufficient. The next major release was late because of the bad quality of the documentation.

The Chinese technical authors had weekly training. All problems in all documents were examined using a spreadsheet. The Chinese technical authors responded with their comments, and the cycle continued until all problems were solved. This method was suitable for the Chinese technical authors, because they wanted to have rules to obey.

To evaluate the outsourced technical authors, the UK team used a weighted score sheet, and measured things such as accuracy, completeness, and grammar. As a result, they decided that the Chinese technical authors were not suitable.

Peter found that a different Indian technical authoring agency was used by a different service group in the company. Therefore, the documentation team used that technical authoring agency instead of the one that they had initially worked with (which was a training agency). One senior Indian team member was put with the UK group for a year (the agreement was for 'as long as is necessary'). Putting the team member in the UK highly increased the quality of the documentation. The quality of the Indian technical authors is now almost as good as that of the UK technical authors. However, the cost of the Indian technical authors is also increasing.

From document-centric to data-centric: how specifications have influenced the evolution of technical data delivery

Charles C Cartwright is Director, S1000D Dynamic Publishing at PTC (www.ptc.com). Thus, he knows about the S1000D standard, which is used to create technical documentation.

Charles showed an interesting timeline of events. Here, I write about only some of the most important events about the development of standards.

In 1956, ATA Spec 100 was created for the aircraft industry. ATA Spec 100 was designed for paper publications, and it contains guidelines for content and document format. With ATA Spec 100, information is divided into chapters and groups of chapters.

In 1986, AECMA (now ASD) started to work on a specification to harmonize national and international specifications.

In 1989, S1000D was released. S1000D is a specification for the documentation of all land, sea, and air vehicles. The release was an important event in structured writing. Companies used S1000D because S1000D increases profits and decreases costs.

S1000D uses the concept of 'data modules'. A data module has these properties:

S1000D applies to all machinery that has a long life, and companies outside the aerospace industry are starting to use it. For example, it is used to document wind turbines, power generation equipment, oil and gas equipment, and other types of heavy equipment.

What is the difference between S1000D and DITA? S1000D is good for equipment that has a long life, but DITA is good where equipment has a short life, for example, a computer or a mobile phone. S1000D is good where changes to documentation are important. DITA is good where changes are not important (because equipment typically is replaced, not updated).

You can download a copy of S1000D from the S1000D website (https://s1000d.org/).

How technical authoring UK can compete in the global marketplace

Paul Ballard from 3di Information Solutions (https://3di-info.com) spoke about the risks to the technical authoring profession in the UK. Although there is much that we do not know about the technical authoring profession, the future is good, despite the current economic problems.

Much information about the technical authoring profession in the UK is not known. For example, we do not know how many technical authors there are. What is a technical author? Solicitors spend much time writing. Does that make them technical authors?

Usually, technical authors do not enter the profession directly because no straight career path exists. Approximately 70% of the people in the room showed that technical authoring is a second career for them.

Approximately half the people in the room showed that they had thought about their competitive status. Professional technical authors have many competitors, for example:

Technical authors in the UK have many competitive advantages. We need to understand our strengths, and focus on them. Many technical authors are in a difficult position, and their jobs are candidates for outsourcing.

Technical authors need to be more integrated with the manufacturing process, or they need to be nearer to customers To make their position stronger, technical authors need to be more integrated with the manufacturing process, or they need to be nearer to customers. Now, they are easy to outsource.

Paul thinks that despite the problems, technical authors have a bright future. Things are becoming more complex, and therefore, technical authors are necessary to help customers to use products and services. Regulation is increasing, and the regulations and their implications need to be explained.

Outsourcing may cause some UK technical authors to lose their jobs. However, Paul thinks that internationally, there is more work than there used to be, so that technical authors in the UK can have a smaller piece of a larger market. Our challenges are:

LexisNexis TotalHelp: dynamic DITA publishing

Mike Holt is a documentation consultant. In 2005, he joined the documentation team of 12 people at LexisNexis.

LexisNexis has many products, and each one has a website. Most technical authors wanted to write content, not work on the technical parts of website development. Some technical authors were not comfortable with using markup or DITA topic maps. There was no clear reading sequence between topics.

To solve these problems, Mike developed TotalHelp. TotalHelp is a mechanism for supplying user assistance. The content is XML, which can be stored in flat files, or in a database. The content passes through different processing steps, and is output typically as XHTML or as XML.

The architecture uses the Model-View-Controller (https://learn.microsoft.com/en-us/previous-versions/msp-n-p/ff649643(v=pandp.10)) mechanism, in which the business logic is separate from the user interface:

Mike demonstrated TotalHelp. He explained that the tree view was dynamically created using metadata. The content for related topics panes, reference panes, and 'how do I?' panes were all automatically created.

Algorithms calculate the 'relatedness' of topics, and technical authors can add information about relatedness to supplement the algorithms.

TotalHelp is a success, and now many of the products from LexisNexis use it.

Minimalism in complex knowledge domains: can it be done?

Galyna Key is a technical author at Autodesk (www.autodesk.co.uk). Galyna uses minimalism in her documentation, which is used in complex knowledge domains.

Minimalism has been evaluated in simple knowledge domains. Some research shows that minimalism helps readers. But, other research shows the opposite. Galyna explained some of the challenges that her team had in their complex knowledge domain.

The rules of minimalism cause some questions. For example, in the context of action-centred documentation:

According to minimalism, tasks must be real and meaningful. Therefore, these questions occur:

In a minimalist document, if error recovery is explained at all applicable steps in a task, there will be much repeated information in the document. Possibly, users will be frustrated with the unnecessary information about all the problems (users will not make all the errors that they possibly can make).

The information structure of a minimalist document can be shown as follows:

At the lowest level, there are actions. A task is a set of actions plus recovery information. The top level is a business process, which is a set of tasks that are rooted in the knowledge domain.

Galyna says that minimalist documents must contain not only procedures. Users need more information. As with all types of documentation, two problems that technical authors have are deciding on the level of detail and organizing the tasks.

Towards an ISO standard for technical communications

Early in 2008, BSI contacted the ISTC to discuss the possible development of a Publicly Available Specification (PAS) for technical communications. Simon Butler, the ISTC president, explained the proposal.

A Publicly Available Specification is between an in-house standard and an international standard. (The objective is that the PAS will finally become an international standard.) Many standards for technical communication exist, but they are mostly about the content and production of documentation. Some of the new 265nn ISO standards for technical communication contain information about tasks that technical communicators do.

However, no national standard specifies these important topics:

If the PAS project starts (a proposal to the ISTC Council has been given outline approval), the first task will be to find the knowledge that is missing. Parts of the National Occupational Standards, which the ISTC published in 1999, will possibly be used in the PAS.

As a sponsor of the PAS, the ISTC would do these tasks:

What are the next steps in the process? If the project starts, the ISTC will need to engage stakeholders and find a few stakeholders that will give financial aid. As the project continues, people will be needed as contributors, reviewers, and standards authors (BSI will train them).

Getting to know your wiki

In the spring 2007 and autumn 2007 issues of Communicator, Katja McLaughlin explained how to set up a wiki. In her presentation, she expanded on some of the topics in those articles.

Sumerian needed a method for sharing knowledge between all personnel. Before the wiki was established, documents at Sumerian were in many formats: Microsoft Word, PDF, and HTML. Navigating the different document sets was not easy. Checking documents in and out of the content management system caused only small delays, but for some contributors who make only occasional changes, the delays were a large problem.

To increase the use of the wiki after it was established, Sumerian did the following:

People asked about the accuracy of the information in the wiki. They were assured that other contributors evaluate the content and correct errors, and that the lack of ownership was part of the collaborative authoring strategy.

Wiki pages are not sorted as a tree view, and some people were confused by this new navigation method, which is why Sumerian offered education about features that make wikis different. Additionally, the main page needed good hyperlinks to content to help people get started.

To prevent the risk of repeated information, difficult navigation, and confusion about whether content was current, readers were encouraged to tell each other about problems and to work as a collaborative authoring team to correct errors.

Katja recommended the following resources:

Documenting for developers—the Symbian story

Symbian supplies an operating system for mobile devices. The operating system is large and complex. The software developers who use the operating system need clear documentation, and Symbian needs technical authors with strong technical skills. David Black, Head of Documentation, explained how the technical authors were recruited.

The first step of recruitment is to get investment. You need a business case, and you need to explain to management what the costs will be if the company does not invest.

David gave these comments about recruitment:

To develop the documentation, software development methods were used with the documentation. Technical authors were put with the software development teams, instead of being physically separate in a documentation department. As far as possible, the documentation structure matched the software code.

Getting more investment after the initial investment is frequently difficult. However, if you can show management that you did well with the resources that you had, you can then say that you can do much more with more money.

The recruitment strategy worked well:

The future will be busy. Symbian Foundation (https://licensing.symbian.org) is a new organization that will include technical authors who will move from Symbian. They will need to publish the documents from 17 companies that are part of the Symbian Foundation.

Closing keynote address: web technology update

To end the conference, Joe Welinske from WritersUA spoke about open source technologies and standards for web-based development.

Although standards give continuity and familiarity, they can decrease creativity. They require support from user agents, and if a web browser does not conform to a standard, the standard is useless.

To support everything is not possible. Some combinations are not practical. If software is not compatible, problems can occur. For example, when Google's Chrome web browser was released, RoboHelp did not work correctly with it.

Joe spoke about different help formats. My favourite example uses Flash, and shows how to use the Verizon Wireless XV6800 mobile device.

Summary

The ISTC conference gave an excellent insight into the technical communication industry. In this short review, I cannot do justice to the presentations. I learnt much, not only at the presentations, but also from the informal networking, and from following up on information that I learnt during the conference.

RSS feed

© TechScribe, Sheffield, South Yorkshire. Page updated 2009-02-03

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