Technical Communication UK 2009
The Technical Communication UK (https://istc.org.uk/tcuk) 2009 conference was in Derby, 22-24 September. Mike Unwalla reports on the presentations that he attended.
Topic-based authoring: getting your feet wet
On Tuesday, Greg Urban and Linda Urban gave a two-part workshop about topic-based authoring. Both parts were excellent. In the morning, the presenters discussed topic-based authoring.
Topic-based authoring is not new. For example, in 1998, Linda learnt about topic-based authoring at HP. Information Mapping is a type of topic-based authoring.
Frequently, topic-based authoring is structured writing. However, structured writing does not need to be topic-based. For example, DocBook is designed for structured writing, but the structure is for a book. Structured writing conforms to a pattern.
'Modular content' means that content can be used more than one time. Modules can be large or small, for example, chapters, or sentences.
Topic-based authoring is important to DITA, but it is not equal to DITA. You can write topic-based documents without DITA.
Topics can have different 'types'. For example, typical topic types in DITA are concept, procedure, and reference. A particular topic type can contain more than one information type.
In the afternoon, many practical exercises helped me to improve my skills with topic-based authoring. I enjoyed the day very much.
Keynote address: Smart authoring for a smarter planet
More than 1000 people work as information developers at IBM (www.ibm.com.uk). Peter Anghelides (https://peteranghelides.wordpress.com) spoke about IBM's documentation. The documentation has 4 features:
- Obvious. If a product is obvious, documentation is not necessary. Ideally, documentation is not necessary. However, IBM's software is complex. Therefore, documentation is necessary
- Online. IBM is the second largest publisher in the world. (The US government is the largest publisher.) IBM put documentation online to decrease costs. However, online documentation shows customers that IBM is an 'e-company'. IBM's customers want 'just-in-time' documentation. In the past, documentation was very large. Sometimes, documentation arrived at customer sites on pallets.
- Open. The documentation is freely available. The documentation is created with open source software, and it conforms to open standards.
- Organized. In the past, customers sometimes could not find information, and they were not sure if the information was applicable to the software version that they used. Now, IBM's strategy is to supply "the right content to the right person at the right time in the right form."
Peter thinks that in the future, technical authors will create less documentation for consumers, and more documentation for technical people.
Pattern language for information architecture
According to Wikipedia (www.wikipedia.org), a pattern language is "a structured method of describing good design practices, within a field of expertise."
Matthew Ellison (www.ellisonconsulting.com) explained that the concept of 'pattern language' started in architecture (A pattern language, Christopher Alexander, Sara Ishikawa, Murray Silverstein). Alexander explains that each pattern identifies a problem that occurs many times, and gives an answer.
For example, think about an area in which to wait. The problem is that the process of waiting has some conflicts. The answer is to create a situation that makes waiting a good thing. Give people other things to do during the waiting time. For example, supply newspapers or coffee.
Matthew gave examples of how patterns can be applied to the design of user interfaces:
- Problem: users need to know the location of a page in online content. Answer: use breadcrumbs to show the position of the page in the structure of the document.
- Problem: some users know a term, and other users do not know that term. Answer: use pop-up windows to show definitions.
You cannot design the patterns. You find a good pattern by monitoring what gives good results and what gives bad results. You can specify the patterns in different ways. For example, you can use pattern statements, or a style guide.
If you can write an article, you can write anything
Kim Schrantz-Berquist explained 5 different methods that help to make text clear and interesting (https://how-to-write.org).
- 5Ws + H. This method is used frequently in journalism. The 5Ws mean who, what, when, where, and why. H means how. Use the method to tell readers what they probably need to know next.
- Inverted pyramid. Put the most important information at the start of a document. Sometimes, reading to the end of a document is not necessary. The inverted pyramid compares to the essay method, where conclusions come at the end of a document. To use the inverted pyramid style, use 5Ws + H, and add clauses.
- Question and answer method. The questions can be created by the writer, or they can be real questions from readers. Questions that are not answered cause readers to lose attention.
- Hierarchies. Information has different relationships with other information. Use different conjunctive adverbs and comparative adverbs to connect information. Adverbs such as 'also', 'and', and 'in addition' give equal emphasis to different information. If information has different importance, use connectors such as 'more importantly' and 'least of all'. To show sequence, use connectors such as 'before', 'then', and 'finally'.
- Sentence flow. Use sentence flow to connect sentences or paragraphs. To use this method, read the end and the start of sentences to find words that are not in the best location. For example, do not write:
Instead, write:
Migrating to XML: from legacy content conversion to authoring
Autodata (www.autodata-group.com/uk/) has approximately 150 employees in 7 countries. In 2008, sales were £13 million.
Gabriele Ostermaier said that in the past, Autodata used different markup methods to create repair manuals. The limits of markup are as follows:
- Technical authors used tags inconsistently.
- Tags contain formatting information.
- Tags do not have an end delimiter.
To improve the production process, the technical authoring team wanted to use XML. The team had 2 options:
The technical authoring team decided to create the documentation in-house, instead of outsourcing the task. However, the schema design was outsourced.
The technical authoring team used 8 temporary technical authors who were trained on the job. The temporary technical authors changed legacy documentation to XML. Some of the conversion was done with VB scripts, but the technical authors had to make sure that the output was correct.
The technical authors changed more than 136,000 files in 16 languages.
The conversion was a start for continuous development. The primary lesson that the team learnt was that they did not use sufficient metadata.
Visual attention: a psychologist's perspective
Chris Atherton's presentation was one of my favourite presentations. Chris is interested in how the brain is related to thinking, perception, attention, and memory. She says, "Your brain is lazy."
Most technical communicators think that many lines of text on a presentation slide is not good. Chris explained the reason.
Chris discussed Gestalt grouping. She showed the following picture.
Chris asked us to solve the following problem. Put a pen on one dot. Without removing the pen from the paper, draw 4 straight lines that go through the dots. A dot can have only one line through it. A line can go across another line.
I did not find the answer, but the answer is simple.
Cognitive load is the amount of work that is necessary to learn something. The 'intrinsic cognitive load' is dependent on the topic. The 'extraneous cognitive load' is the additional work that is caused by the learning conditions. Good instructional design decreases the extraneous cognitive load.
In practice, to decrease the extraneous cognitive load, give different parts of the brain different jobs at the same time. Written language and spoken language are processed in one part of the brain. Pictures are processed in a different part of the brain. Therefore, when you speak and use presentation slides, make sure that each presentation slide has only a small amount of text, or a small amount of text and a picture.
To learn more about how to give a good presentation, see 'Finite Attention Span' (https://finiteattentionspan.wordpress.com).
Authors don't do publishing
Steve Cripps spoke about one publishing company, in which approximately 30 technical authors used a mix of FrameMaker, InDesign, Microsoft Word, and PageMaker. Management wanted to use structured writing. Some technical authors did not want to use structured writing.
Steve explained how the company did a 6-month trial. Two technical authors and the support team used a small CMS and Arbortext Editor. The technical authors were not responsible for the appearance of the documentation. Therefore, the technical authors did not need a WYSIWYG editor.
The results of the trial were good:
- The technical authors liked the new method, because they worked on only the content.
- The technical authors did not waste their time formatting documents. Therefore, the new method decreased the work of the technical authors.
- The technical authors needed less support, although initially they needed more support.
- The two technical authors who did the trial 'sold' the new method to the other technical authors.
Sustainable energy — without the hot air
Niall Mansfield spoke about the development of the book, Sustainable energy — without the hot air (www.withouthotair.com) by David J.C. MacKay. Niall is David's editor.
David wrote the book because when people speak about climate change, they usually give only opinions. People do not give numbers to support their opinions. David was tired of hearing that turning off a mobile phone charger can make a practical difference to climate change.
The primary decisions about the design of the book are as follows:
- Use numbers, not adjectives. The book gives facts, and it does not make conclusions.
- Use human-sized units. For example, when you have a bath, you use 5 kWh. If you fly from London to Los Angeles, you use 120,000 kWh, which is equivalent to 33 kWh a day for a year.
- Use graphics to show numbers. Graphics can help to make numbers clear. David compared the number of deaths to birds by wind turbines, cars, and cats (www.inference.org.uk/withouthotair/c10/page_64.shtml). Some people hear that wind turbines kill 30,000 birds a year, and they say, "Don't build wind turbines." However, deaths by wind turbines are small compared to deaths by cats (55,000,000).
- Use simple formulae only, because some people "do not understand Greek." Put technical information at the end of the book.
The book is published with a Creative Commons (https://creativecommons.org/) copyright. Surprisingly, forged paper copies appeared for sale.
The book is attractive, and colour is used well in both the graphics and the text.
How text formatting can enhance the readability and persuasiveness of text
Kath Straub explained that the location of a line break has an effect on the readability of text.
When we speak, we pause to make ideas clear. Kath gave the following example: "The horse raced past the barn fell." Without a pause, the sentence is very difficult to understand. Most people in the room did not understand the sentence. With a pause, the sentence is clearer: "The horse [pause] raced past the barn [pause] fell." Most people understood the sentence. (One person struggled to understand. Kath agreed that the sentence is 'clunky', but it is a good example.)
With text, the equivalent of a pause is a comma. However, sometimes a comma is not possible. The sentence, "the chauffeur annoyed the man with the cigar" can mean two things:
- The chauffeur has a cigar. The chauffeur annoyed the man.
- The man has a cigar. The chauffeur annoyed the man.
In speech, we can pause to make the meaning clear. For example, we can say, "The chauffeur annoyed [pause] the man with the cigar". However, if we write the sentence, we cannot use a comma. (Ideally, we write clear text. Kath gave the example to show that text is not the same as speech.)
ReadSmart is a method that makes text clearer than standard text:
- Spaces between phrases are longer than spaces between words.
- More lines stop at phrase breaks. This results in a very ragged right margin.
In a study, direct mail was sent to 390,000 people. The response rate was 22% higher for the people who got the ReadSmart version of the advertisement.
Except for the ragged right margin, people cannot see the difference between standard text and ReadSmart text.
Why your XML projects keep failing
Bret Freeman said that according to Gartner, in the average organization, 80% of content is not structured. 90% of unstructured information is not managed.
Unstructured content causes problems. For example, there is no control, no consistency, too much repeated work, and a high risk of error.
'Intelligent content management' can solve the problems. Content is controlled, traceable, versioned, consistent, searchable, and reusable. The result is increased sales, and decreased costs.
Bret spoke about where to start with intelligent content management:
- Technology only does not solve problems. Think about the 'big picture'. Do not always buy services that are sold around a product.
- Process is important. Identify the problems, and learn from examples. Use standards, and find a supplier that has experience of your problems.
- Frequently, projects fail because of people. Give people training. Make sure that knowledge workers are involved early in the project. Use external resources to get the necessary skills.
Seven ways to lower costs and raise quality in your documentation
Spencer Garlick said that many organizations invest in 'lean' methods, but they do not do that for their documents. He gave 7 methods that help to increase the quality of documentation.
1, 2, 3. Frequently, the same content is related to more than one product. To decrease the amount of documentation, modularize the content (write in 'chunks'). Use conditional publishing to put the applicable content in a document.
4. Control the technical terms. For the metadata, include information about the status of the term, the validity period, and the source. Make sure that you know about all the alternatives to each preferred term.
5. Control the language. Write simply and consistently. Many languages have only a small number of words. For example, Taki-Taki is a creole that has approximately 750 words. However, a problem with controlled English is that sometimes, controlled English sounds 'choppy'.
6. Do not include 'accidental content'. For example, if you give people an instruction about how to turn off a machine, you can write the instruction in many different ways. Make sure that the text is proofread and reviewed. To decrease the variety of text, use authoring memory.
7. Use single-sourcing.
Rapid advances: the evolution of e-learning development
Andrew Jackson said that in the past, the development of e-learning by an external organization was very expensive.
Now, e-learning is changing. Organizations use a mix of development methods.
By means of an analogy, Andrew showed the problems of e-learning. In the past, people used overhead projectors to show information. Now, we use PowerPoint, but the quality can be very bad. Technology gives people the ability to create bad-quality information.
Some possible trends in e-learning are as follows.
| Trend | Result |
|---|---|
| The term 'e-learning' will disappear | The emphasis will be on knowledge transfer |
| Customized development | Individuals will create content |
| The job of 'instructional designer' will change | Instructional designers will become coaches and mentors |
Therefore, the new problem is how to prevent the e-learning equivalent of bad PowerPoint slides. One option is to use a method such as Information Mapping to get good modular content.
Software to support the development of e-learning needs the following features:
- The software must be powerful, but simple to use.
- The software must be optimized for modular content.
- The software must have good tools for collaboration.
- Workflows must be part of the software.
- Instructional design features must be in the software.
The future vision for technical communicators: are we delivering content or captivating audiences?
R J Jacquez is Senior Product Evangelist for Adobe (www.adobe.com). He said that technical communicators need to use social media to engage readers.
Engagement is important for the following reasons:
- The amount of technical information is quickly increasing. The amount of new technical information doubles every 2 years.
- Social media has changed communication.
- We need to meet the expectations of people who use 'web 2.0'.
For radio to have 50 million listeners, 38 years were necessary. For the Internet to have 50 million users, 4 years were necessary. For Facebook (www.facebook.com) to have 50 million users, 2 years were necessary.
In a survey of 300 high-level executives, 86% said that engagement is important. One third said that insufficient engagement caused their companies to lose business.
According to Jacquez, an engaging experience is accessible, collaborative, compelling, easy to use, personalised, and responsive.
Jacquez spoke about Erik Qualman's Socialnomics (https://socialnomics.net), and gave some interesting facts from the book:
- On the Internet, social networks are now more popular than pornography.
- 1.5 million items of information are shared on Facebook (www.facebook.com) each day.
- 80% of companies use LinkedIn (www.linkedin.com) to find employees.
- YouTube (www.youtube.com) has more than 100 million videos.
- There are more than 200 million blogs.
- 25% of search results are for the world's 20 largest brands.
- 78% of consumers trust the recommendations from other consumers.
To end, Jacquez repeated what he wrote on Twitter (https://twitter.com, hasthtag #TCUK09), "I see technical communicators as 'information facilitators' for their customers via social media platforms like Twitter."
RSS feed