XML isn’t the only way to semantic content

I’ve been on the road speaking at a conference this week, and I’ve been listening to a lot of presentations on technical communication. Many of these were on the importance of having structured, semantic content when you are dealing with large amounts of content that needs to be translated into different languages and published in many different ways. All of these presentations put forward XML-based systems as the solution.

However, XML isn’t the only method for having semantic content. For example, AsciiDoc supports attributes, which can be used to add a semantic descriptions to headings, paragraphs and whole documents. You can use conditions in RoboHelp and Flare to categorise content. You can also store content in a database.

It’s sometimes useful to remember that XML isn’t the only way to semantic content.

 

Our next advanced technical writing training course will be on 22nd March

We’ve just scheduled another of our Advanced technical writing & new trends in technical communication training courses.

“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.”

It will be held on 22nd March, in central London.

Explaining complicated stuff using simple words

Book coverRandall 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?

XKCD cartoon

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.

All our online courses – at a discounted, bundle price

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

New training courses in technical communication are on their way

It might seem like we’ve been quiet recently, but that’s partly because we’ve been working on an academic project that we hope to be announcing towards the end of the year.

As a spin-off from this project, we’re developing new training courses in technical communication. These courses are at a more advanced level than our basic/intermediate courses, and they include more references to academic research.

If you are considering any on-site training for your technical communications team, we can now offer these topics:

  1. What is technical communication?
  2. The business case for technical communication
  3. History of technical writing standards
  4. Usability and user centred design
  5. Project planning and its effect on writing documentation
  6. Researching and scoping documentation
  7. Estimating
  8. Information design and content organisation
  9. Writing the topics – overview
  10. Presenting different types of information
  11. Index, search and metadata
  12. Single sourcing and reusing content
  13. Post writing​
  14. Researching technical communication – where to go
  15. Establishing standards
  16. Governance and maintenance
  17. What skills does a technical communicator need?
  18. Content strategy and technical communication
  19. Trends in technical communication
  20. Visual design
  21. Publishing and delivering information
  22. Managing the documentation project
  23. Metrics/Evaluating documents

We may develop online courses for some of these topics in the future as well.

Is it possible for Technical Authors to write content more quickly?

Approximately 50% of a Technical Author’s day is spent writing. However, when Technical Publications teams look for efficiencies, they tend to focus on the 50% of time spent on non-writing activities, such as researching, reviewing and planning. They assume the content itself cannot be written more quickly. To an extent, they are right, as the querty qwerty keyboard is not an optimal layout.

We’ve been going through a process of transcribing our early e-learning modules, in order to have scripts upon which we can base future course updates. As part of this project, we’ve been using a free application called Plover to help us write the content. With Plover, you have the potential to create content (in Word, RoboHelp, Flare, Oxygen XML etc) at up to 225 words per minute (wpm).

Plover is based on chorded typing. You press more than one key at a time to create words. Chorded typing isn’t new – for example, it was demonstrated in Douglas Engelbart’s famous “The mother of all demos“.

Below is a five minute lightning talk on Plover and some of the emerging hardware:

So far, in my case, I’ve been able to double my typing speed. Realistically, those of us participating in this project at Cherryleaf aim to get to 180 words per minute. The reason for this is that most people speak at 160-180 wpm. At that speed, you are able to transcribe subject matter experts in real time – which means there’s no need to record an interview and then type it up at a later date.

There is a learning curve to this method, but it is based on over 100 years of theory and practice. It is tremendous fun – a bit like learning to use a querty qwerty keyboard for the first time.

Teaching non-readers to read

Cherryleaf has been working on a project which shows people how to teach non-readers to read. We’ve been working with Elizabeth Ainley, who has written a book, go for it!, which can be used to teach illiterate and/or dyslexic adults.

Elizabeth asked Cherryleaf to help her re-write the existing instructions aimed at the adult coaches who will be using go for it! This involved making the instructions clearer, and clarifying the learning outcomes.

Schoolchildren in Sierra Leone have been the first users of the project. It means a 12 year old child who can read can now teach others. The school is run by Miriam mason-Sesay MBE for the Educaid, who sent Elizabeth these photos of the teaching materials in use:

IMG_2713Dyslexia teaching in Sierra Leone

Dyslexia teaching in Sierra Leone