Randall Munroe’s latest book Thing Explainer will be released tomorrow. In the book, Munroe uses line drawings and only the thousand most common words to provide simple explanations for complicated objects.
It’s good practice to use words that are commonly understood. In some industries, Technical Authors have to write using only a limited list of approved words (a “controlled vocabulary”). For example, there are controlled vocabularies for aircraft maintenance manuals, because some maintenance engineers have a only limited amount of English.
Sometimes, the word “stuff” doesn’t help the reader to understand. So what do you do when readers need to understand the small differences between objects, particularly when they can have a big effect on what happens next?
In order to write clearly, there are times when you need to use more than the thousand most common words. Technical Authors deal with this issue by using concept, terms and references topics. When they need to use words that some users might not understand, Technical Authors provide a link (or cross reference ) to another topic. This other topic provides an explanation or a definition of the word or concept. The topic can contain words, images, diagrams, animations or videos to help the user grasp the meaning.
It’s good to use simple words, but it’s more important to make sure the information is clear.
Here are the dates for our next advanced technical writing & new trends course:
- The next public classroom course will be held on 28th January 2016, at our training centre in central London (SW7).
- A live Web course, for delegates based outside the UK, will be held on 6 & 7 January 2016 (2 x 3 hour sessions).
Discover the advanced new writing styles emerging in technical communication by attending Cherryleaf’s popular training course. Don’t get left behind: past clients include technical communicators from Citrix, GE, IBM UK, Lloyds Banking Group, Sage plc, Schlumberger, Tekla and Visa International.
See Advanced technical writing & new trends in technical communication training.
Judging by Social Media last week, there were many strong opinions at the tekom tcworld conference towards the DITA authoring standard and the associated tools. It seemed, as the philosopher Swift once said, “Haters gonna hate”, and, by inference, “Hypers gonna hype”.
Eliot Kimber provided an interesting summary in a post to the DITA users group forum (Trip Report: Tekom 2015, DITA vs Walled Garden CCMS Systems):
“For background, Germany has had several SGML- and XML-based component content management system products available since the mid 90’s, of which Schema is probably the best known. These systems use their own XML models and are highly optimized for the needs of the German machinery industry…These products are widely deployed in Germany and other European countries. DITA poses a problem for these products to the degree that they are not able to directly support DITA markup internally, for whatever reason, e.g., having been architected around a specific XML model such that supporting other models is difficult. So there is a clear and understandable tension between the vendors and happy users of these products and the adoption of DITA…
…It’s clear to me that DITA is gaining traction in Europe and, slowly, in Germany but that the DITA CCMS vendors will need to step up their game if they want to compete head-to-head against entrenched systems like Schema and Acolada. Likewise, the DITA community needs to do a better job of educating both tools vendors and potential DITA users if we expect them to be both accepting of DITA and successful in their attempts to implement and use it.”
This may have led those who are asking, do I need DITA?, to come away from the conference more confused than before. So, we thought it might be useful to provide a rough guide to whether it’s worth adopting DITA:
You probably don’t need DITA if:
- The way the content looks to the user is the most important issue.
- You have fewer than four writers.
- You write narrative content.
- You have limited budgets for tools, training and migration.
- You don’t have the time to deal with the issues around changing working methods.
- Your content has a “shelf life” of less than two years.
- You use a lot of graphics with annotations.
- You need to customise outputs [added] for individual documents [added] (such as PDFs).
- The cost of migrating existing content will be expensive.
- You want the presentation layer embedded with the content layer.
- You don’t want to work within strict rules regarding how topics are written (where content is marked up semantically).
- You need to use the tools used by developers or the marketing department.
- You want a simple information architecture.
You might need DITA if:
- You need to write to (and enforce) a standard.
- You need to localise content into many languages.
- You have more than four writers.
- You want to write semantically.
- You need a more efficient authoring, [added] reviewing [added] and publishing process.
- You create many variations of the same document.
- You want intelligent content that can adapt to different users and contexts.
- You are spending too much time on formatting content.
- You need to re-use content in different projects and different contexts, and make those topics accessible to other writing teams who might want to re-use them.
- You need to establish a controlled vocabulary and taxonomy.
- You want content validated for consistency.
- You want automated publishing.
You probably do need DITA if:
- You need to share content with other organisations.
- Your content will need to last more than 30 years.
- You want content to be stored in an open data standard, independent of any tool.
- You don’t want to be tied into a specific authoring tool, content management system or publishing/rendering engine.
- You need transclusion (where an element can replace itself with the content of a like element elsewhere) across a range of media.
- You want to have a way of generalising back to a common standard.
Do you agree?
Please share your thoughts below.
It’s not quite 2016 yet, but here are our five predictions for technical communication in 2016 and beyond.
Here are our predictions:
1. As documentation becomes to be seen more as part of product design, so the technical writing process will become part of the product development process
We’re likely to see reviews and version control follow the developers processes, and be managed via tools such as Git.
2. Markdown will break out from being an authoring format for developers and into the mainstream
Markdown offers separation of look and feel, variables, topic-based authoring and single sourcing, in a tools-neutral, simple to use, format. At a push, you can also do conditional publishing, too (information typing is lacking, though). Because it is used by developers themselves, we’re likely to see the tools develop at a rapid pace, and become more powerful and easier to use.
3. More technical communicators will use Lean methods when working in an Agile environment
Lean is something we’ve been discussing for a number of years, and seems to have picked up as a new topic at conferences recently.
4. We’ll see greater use of the imperative voice in topic titles
We explored this earlier in the year – The decline of the gerund in technical documentation?
5. The popular Help authoring tools will be able to generate embedded Help and on-boarding screens
This is more a wish, but it wouldn’t surprise us if the Help authoring tools will enable authors to single-source Help text that will be embedded in the UI itself or appear within on-boarding screens.
Do you agree? What you see as future trends? Use the Comments box to let us know.
We’re carrying out a short survey into the biggest issues relating to technical communication you think you’ll face in 2016 .
To participate, please complete the questionnaire below (alternatively, use this link to the survey):
In the radio series, A History of the World in 100 Objects, Neil MacGregor, Director of the British Museum, described the oldest man-made object in the museum – the Olduvai stone chopping tool. This was made approximately 1.8 million years ago in Tanzania, where the first humans originated.
MacGregor explained the tool has more than six chippings that sharpened this rock into a tool, when it only need two. He said:
“Those chips tell us that right from the beginning, we, unlike other animals, have wanted to make things more complicated than they need to be.”
Complexity, it appears, has been part of product design and manufacture right from the beginning. Did the need for user instructions follow shortly afterwards?
You can now sign up for all of Cherryleaf’s popular online training courses at a discounted price!
This bundle provides you with access to:
By purchasing this bundle, you’ll save £180 ex VAT. That’s a discount of 38%.
See: Cherryleaf training course bundle – all our online courses at a discounted price
Here is a diagram that shows the different types of User Assistance that can help users as they progress through the customer journey:
Supporting the user through the customer journey has become more important, partly because the subscription, “try before you buy”, sales model means users can stop being a paying customer at a moment’s notice. Today, all of the information you provide, both pre- and post- sales, needs to provide the same consistent, high quality, experience to the user.
Have we missed anything out? Let us know if you think the image should be changed in any way.