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 (www.tedopres.com) explained the advantages of controlled language.
Some risks of not controlling language are:
- Confused or frustrated readers
- Legal liability
- Damage to equipment
- Increased localization costs
- Increased support costs.
One of the participants 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:
- 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.
- Train the technical writers.
- 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 principles, 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.
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' (http://performancesupport.blogspot.com/2008/01/invitation-to-our-performance-support.html), which are the times when people need help:
- When learning for the first time
- When learning more
- When remembering or applying what has been learnt
- When things go wrong
- When things change.
Koen Lourdon from Trisoft says that customer-centred documentation has these properties:
- It is in the language of the customer.
- It is for specified products. It does not contain information about the full product set.
- Units of measurement are those that the customer uses.
- It is adapted for a reader's level of ability.
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:
- Yes/no conditions
- Range conditions, for example, 'version x to version y inclusive'
- Conditions that are dependent on a specified value.
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.
The authors at Alliance and Leicester (www.alliance-leicester.co.uk) 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 deal 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.
When Audrey became responsible for the intranet, some of the content was very bad quality.
Some of the problems were:
- There were many stakeholders, and the content for one type did not apply to other types.
- Different groups of stakeholders did not get on well.
- The employees who dealt with customers were not respected by other employees.
- People thought that they were special, and 'my rules do not apply to me'.
- Authors and users conflicted. Authors wrote to achieve their objectives, but users wanted what they needed, not always what the authors wrote.
- Some authors had bad writing skills.
Web pages had bad structure, and had these problems:
- Web pages appeared differently. Although users want consistency, authors thought that differences made web pages look good.
- Web pages contained too many words, and the tone was not suitable for the audience.
- Web pages were difficult to use.
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 suffered 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.
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:
- Select an Indian technical authoring agency.
- Train the Indian technical authors to use Epic Editor and XML
- Recruit six Chinese technical authors.
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). Therefore, he is qualified to speak 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 1000 was created for the aircraft industry. ATA 1000 was designed for paper publications, and it contains guidelines for content and document format. With ATA 1000, 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:
- It is a small item of information, for example, a removal, installation, or servicing operation.
- It contains metadata to help technical authors to find and to use the data module.
- It can be merged with other data modules to create a publication.
- It can be used in many publications.
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 the S1000D specification from the official S1000D website (http://public.s1000d.org/).
Paul Ballard from 3di Information Solutions (www.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:
- Technology. Because there are software systems and authoring tools, some managers think that they do not technical authors.
- India. Technical authors in India are much cheaper than technical authors in the UK.
- Web 2.0. User-generated content is very popular now. If users create content without payment, why do businesses need to employ technical authors?
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.
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:
- Independently, compete for our piece of the market
- Together, make the market larger
- Extend our influence by becoming more valuable.
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 either in flat files, or in a database. The content passes through different processing steps, and is output typically as XHTML or as XML.
- The model is the data. The model is the technical author's area.
- The view renders the model into a user interface. For example, it automatically creates suitable buttons. If the text is German, the buttons will be German. The view is the website developer's area.
- The controller is the framework that lets the mechanism work. An example is Apache Cocoon, which is an XML publishing framework. The controller is the engineer's area.
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.
TotalHelp is a success, and now many of the products from LexisNexis use it.
Minimalism has been evaluated in simple knowledge domains. Some previous research shows that minimalism helps readers. However, other research shows the opposite. Galyna explained some of the challenges that her team had in their complex knowledge domain.
The principles of minimalism cause some questions. For example, in the context of action-centred documentation:
- Does the opportunity to take immediate action mean that declarative information is not necessary in documentation?
- How do we help a user to explore a product?
- Does a user want to explore a product, or only to use the product?
According to minimalism, tasks must be real and meaningful. Therefore, these questions occur:
- What is a real task, specially in a complex knowledge domain?
- If software is used in different disciplines, can a task be set in many domains at the same time?
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:
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.
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:
- The process of developing technical publications
- The skills and the training that technical communicators need
- The requirements for conformity with legislation.
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 be responsible for the following:
- Determine the scope of the PAS.
- Make sure that the needs of all stakeholders are met.
- Make sure that the project does not conflict with other standards.
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).
For comments about the PAS, or to offer your services, contact Simon Butler (email@example.com).
For more information, see the BSI web page about publicly available specifications (www.bsigroup.com/en/ProductServices/About-Kitemark/Consumer-Information/What-are-standards/PAS/).
Sumerian (www.sumerian.com) 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:
- Encourage key people in the teams to become interested in the wiki
- Remove blockages to editing
- Offer education if people needed it.
People asked about the reliability 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 intentionally 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 overcome 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:
- Wikipatternsis a toolbox of patterns, and a guide to the steps of establishing a wiki.
- WikiMatrix (www.wikimatrix.org) is a tool for comparing wikis.
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:
- Define a necessary skill level, and then test the technical authors. Without exception, technical authors who fail a test must not be recruited.
- Build a team, and recruit technical authors who have complementary skills.
- Sometimes, software developers can become technical authors.
- Using technical authors in India and China is possible, if there is sufficient editorial control.
- Keeping technical authors is the only way to avoid recruitment.
To develop the documentation, software development methods were used with the documentation. Technical authors were embedded in 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:
- In 18 months, the team increased from 13 to 49 technical authors. They now work at four sites around the world, and half the technical authors are in India or China.
- In two years, only one technical author has left the team.
- Customer satisfaction increased from 22% to 61%. There is a delay between supplying documentation and measuring customer satisfaction, and David thinks customer satisfaction will increase more.
The future will be busy. Symbian Foundation (http://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.
To end the conference, Joe Welinske from WritersUA (www.writersua.com) 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. Compatibility is sometimes a problem. 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 (http://support.verizonwireless.com/swf/xv6800/simulator.htm).
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.