Farewell?

Adrian Warman has started a series of posts on his blog about the future of technical writing. In today’s post, Farewell to the technical writer, he argues the traditional role of a technical writer is no more:

“Marketing and sales specialists, designers, developers, developer advocates, support and operational people – indeed almost anyone associated with the overall creation and delivery of a service or product – are all perfectly capable of creating content that might not be perfect, but is good enough.”

There are many good points in Adrian’s post, and we look forward to the rest in this series. However, there is a counter argument to be made:

  1. Why do organisations still buy Flare or RoboHelp, when they could use Markdown? We would suggest it’s because projects often become more complex over time. You start to need support more than one version of a product (the professional and the standard version, for example); you need to support more than release version; you end up developing bespoke versions for your biggest customer; you need to localise the content for international markets. As the products become more complex, so can the documentation, and it can be a struggle to manage this complexity in an efficient way with Markdown.
  2. While the writing can be straightforward, the publishing process for Markdown content can be complex.
  3. If people have two responsibilities (code and write user content), one of those tasks may be not given the time and attention it needs. It might be better to have one person focusing on a single task.
  4. Only half the time in a documentation project is actually spent on writing. There’s a lot of planning and research that should go on before that into what users need from the content. Programmers may struggle with that aspect (although UX developers less so).
  5. A Technical Author might be cheaper than a programmer or a UX developer. If you can free their time, by delegating the writing activity to a Technical Author, you might enable them to focus on more productive activities.

The traditional role of a Technical Author is certainly changing, and there is likely to be a more collaborative authoring process. However, the Technical Author can still add value.

Review: Modern Technical Writing by Andrew Etter

Andrew Etter has written a short, Kindle ebook called “Modern Technical Writing: An Introduction to Software Documentation“. The book is Andrew’s personal view of technical communication, based on his experience of being a technical communicator in Silicon Valley.

It neatly describes the “Docs-like-code” approach to technical writing, and it challenges the impulse to write about everything. It describes Andrew’s experience of creating documentation in lightweight markup languages, such as ReStructured Text and Markdown, and using GitHub and static site generators to manage and publish the content.

Overall, I enjoyed reading the book. Andrew describes the benefits from following his approach. Ideally, I’d like to have seen more information and evidence to justify his opinions against other authoring tools. Microsoft Word might be a better choice than Markdown if you need to include complex images, tables or numbered lists. A Content Management System might be a better choice than a static website generator, if you want to provide intelligent content that modifies content to suit different users. The need to manage localised content (in multiple languages) might be easier to accomplish in DITA or MadCap Flare than by using GitHub and Markdown files.

Having said that, the book provides a useful insight into a increasingly common approach to documenting software applications.

New note-taking methods for technical communicators

Note-taking is an important part of a technical communication process. A typical project can move from the account manager to the project manager, and then onto the technical communicator.  Sharing information gathered at client meetings with project team members is often done through internal meetings and phone calls, handover documents written in Word, and other related files uploaded to a SharePoint folder. This type of approach works, but it can be slow and time-consuming.

There are some new(ish) note-taking approaches for students that might also work for technical communicators. We’ve described them below.

Reusable notebooks

The Rocketbook Wave and the upcoming Everlast Notebook are reusable paper notebooks where you transfer your notes into the Cloud using your smartphone. Both notebooks work by you using Pilot FriXion pens. In the case of the Rocketbook Wave, you can erase your notes using your microwave oven (or hairdryer) and reuse the notebook. With the Everlast, erasing is done using a damp cloth.

Everlast notebook

While notebook costs and storage issues are important to students, they are unlikely to be of much concern to technical communicators. You could use the same note-taking system, but with different “hardware”.

The “Bullet Journal” method of note-taking

The Rocketbook notebooks contain dotted paper pages, similar to the Leuchtturm 1917 dotted notebooks, and they are often used in conjunction with the Bullet Journal method of note-taking:

We’ve yet to test the Bullet Journal method, but it might mean that it’s possible for others to read handwritten notes and reduce the need to transcribe them into written notes.

Transferring your notes into the Cloud

There are three popular Cloud storage systems for note-taking: Evernote, Microsoft OneNote and Google Keep. You can use your smartphone to scan your notes and upload them as images to the Cloud. The dotted paper notebooks, such as the Leuchtturm 1917, should improve the scanning image quality.

You can organise your notes into electronic notebooks within these applications, and also add tags to add metadata (See I’ve Been Using Evernote All Wrong. Here’s Why It’s Actually Amazing).

Into those online notebooks, you can also clip web pages and insert files, such as Word documents. It’s never easy to get everyone to use a new application, so OneNote has the advantage of being part of the Office 365 suite and easily integrated with SharePoint. Unfortunately, custom tags can’t be created currently in OneNote for Mac, and this may be an issue for some users.

Which methods do you use?

Please about share your ideas and suggestions below.

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?

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: