Beta release of our Revising and Editing Content course

We’ve just published, as a beta release, our latest e-learning course: Revising and Editing Content.

It covers the following topics:

  • Editing
  • Revising content
  • Revising tools
  • Editing and revising exercises
  • Getting your content reviewed
  • The relationship between editors and writers

WriteLessons screenshotRevising and Editing Content is available as part of WriteLessons, which provides you with access to a range of e-learning courses in technical communication.

You have access to all of the courses, which you can take at your own pace.

Predictions for technical communication in 2017 and beyond

Our predictions for 2017 are…the same as they were for 2016! Having said that, there are a few adjustments we can make to the comments we made last year. Below, you’ll see our 2016 predictions In italics and some thoughts for 2017:

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.

This trend now has a name: “documentation as code” (or “docs like code”). This is partly a reaction to more projects following the Agile methodology, with fast and frequent releases and a team-based approach to projects.

Markdown will break out from being an authoring format for developers and into the mainstream.

Markdown is now used for documenting some Cloud applications at IBM, so it’s gaining some well-known users now. We’re likely to see further developments with Cloud-based collaborative authoring tools (such as Corilla, Forestry and CraftCMS). We may also see more use of markup languages that have semantic capabilities as well, such as AsciiDoc.

More technical communicators will use Lean methods when working in an Agile environment.

It’s still early days for Lean in technical communication, but at last week’s “Agile the Docs” conference, we did see an example of how Lean had been used by Worldpay to identify where there were bottlenecks and waste in their writing process.

We’ll see greater use of the imperative voice in topic titles

This continues to be a trend.

The popular Help authoring tools will be able to generate embedded Help and on-boarding screens.

This was more a wish, and it didn’t happen. We also hoped for Markdown support, but that also didn’t come to pass. The popular authoring tools have added more support for Git and similar tools, and working collaboratively in the Cloud. They have improved.

What trends do you predict for 2017?

Changes to #4175 Contract Technical Author, Swindon

We’ve just amended the job description for the contract vacancy #4175 Contract Technical Author, Swindon. This project involves working on Cloud-based applications, rather than enterprise software, which means the content will be written in Markdown rather than DITA.

Ideally, you will have experience in the following areas:

  • Developing web-based online Help
  • Working in an Agile environment
  • Cloud-based solutions
  • Video-based instruction (although is less important).

Apologies for any confusion caused.

See #4175 Contract Technical Author, Swindon.

IKEA “How to Build” videos: a review

Although IKEA has been publishing instructional videos on how to build their products since 2012, we’ve only just come across them. The videos feature real people assembling the furniture, plus some tips on how to carry out certain tasks.

IKEA USA

IKEA USA has eight “How to build videos”, which you can access from the IKEA USA website or IKEA’s YouTube channel:

The videos are mostly visual, and there isn’t any narration. They are between 3 minutes and 12 minutes in duration. As with many videos, it doesn’t really get started until after the first 15 seconds.

Overall, they are very good:

  • The plain background helps you focus on the furniture.
  • The close-up instructional speech bubbles are informative.
  • The animated arrows do a very good job at  highlighting the location of holes.
  • There are zoom-in shots of specific actions.

While the paper instructions tend to stick to a single viewpoint, the video shows the assembly from different angles.

The last video was made in 2015. Why did IKEA stop making them? We don’t know if they have covered all the of the products that would benefit from video instructions, or they ran out of time/money/enthusiasm.

IKEA Italia

IKEA Italia has a similar YouTube channel. This contains translated versions of the IKEA USA assembly instruction videos, plus some assembly instructions from 2016 that have a British narrator.

These videos are much more driven by narrated instructions, and are shorter in length. I suspect this style was cheaper to produce. These videos also work well, as long as you speak English.

Fan videos

There are unofficial IKEA instructional videos on YouTube as well, some of which take a less conventional approach:

Writing documentation in an Industry 4.0 world

Industry 4.0 must be one of the “words of 2016′. We’re seeing a number of discussions on how this will impact on instructional design and User Assistance.

Ray Gallon has blogged on the question, what role should you have in machine-machine information?, exploring the differences between automatic, programmed dialogues, and non-programmed ones. Sarah O’Keefe has also blogged on the German initiative called iiRDS, the Intelligent Information Request and Delivery Standard.

It’s probably too early to form any firm conclusions on the impact Industry 4.0 will make, but it seems like some of the other trends we’ve highlighted this year are following a similar direction – documentation chatbots (docsbots), content as an API and treating documentation as code. There are similarities with iiRDS and APIs in looking at methods for content interchange, although it’s fair to ask, does the technical communication community need yet another standard?

Standards are like toothbrushes - we all know they're a good idea but we don't want to use somebody else's

Alternatives to Word and PDF for policies and procedures documents

In addition to writing user documentation for software and IT hardware, Cherryleaf also writes policies and procedures. In this post, we look at approaches to writing these types of documents.

A lot of policies and procedures documents are written in Microsoft Word and published as PDFs. Word is an application that everyone knows and has on their machine, and PDF is a format that everyone can view. There are, unfortunately, some downsides to this approach. People tend to print out these formats, as it’s easier to read the document that way than online; this means you have to ensure people print out the latest version, whenever the content is updated. From a writer’s perspective, it can be hard to reuse content across different documents, in the same developers reuse bits of code. Instead, the reader has to jump from one section to the next.

Designing content for reading online can help ensure readers are using the latest version, but there still needs to be the capability to provide a printed copy.  You also need something that can be used by non-professional writers to create content.

So what are the alternatives to Word?

Here are a couple of ideas:

1. A wiki-based or wiki-like approach

You can separate the formatting from the content, and generate paper, Word and online versions. You can also have some embedded content (such as warnings) in pages. They provide easy to use authoring environments. The downside can be that it’s hard to make changes across the site – you have to change pages individually.

2. Markdown or AsciiDoc

You can separate the formatting from the content, and generate paper, Word and online versions. You can also have embedded content (such as warnings) in pages. They provide easy to use authoring environments, but they do not often provide a WYSIWYG view to the writer.

Content can be stored as text files, in a repository, so it’s easy for anyone to submit a suggested change. There are now applications that can provide content management, but otherwise you may be creating a bespoke solution for your situation.

See also: Cutting and pasting content into Word documents – Is there a better way?