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.

Policies and procedures as an API

Here’s a trend that didn’t make our list of predictions for 2017 – having company policies and procedures accessible via an Application Programming Interface (API).

API is a term used to describe mechanisms that allow an application to access data or functionality provided by another application, system or service. For example, if your policies and procedures were accessible via an API, they could be embedded or used in other systems within your organisation. APIs offer connectivity, flexibility and future-proofing.

Instead of staff having to look up procedures in a manual or on an intranet, the official guidance or instructions could be embedded into the applications and forms they’re using. Developers could save time by connecting the application they’re developing to the API. They wouldn’t need to write the information, and staff would always be presented with the official, definitive policy or procedure.

You’re still able to create policy and procedure documents, as a web page or in paper format.

This prediction didn’t make the list because it relates mostly to business documentation rather than technical documentation, and we’re unlikely to see many examples of it within the next 12 months. In practice, the content might be managed by a headless CMS; however, the approach would remain the same. Perhaps the NHS and other organisations in the healthcare sector will be the first to take of this approach.

See also: Cherryeaf’s policies and procedures writing services

What do you think of this prediction? Please share your thoughts below.

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?

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

Thyssenkrupp to make HoloLens goggles available to field-service staff

Thyssenkrupp is making Microsoft’s HoloLens goggles available to field-service staff, to assist them in diagnosing and repairing elevators.

“HoloLens with Skype capabilities enables over 24,000 thyssenkrupp technicians to receive remote assistance by subject matter experts who can provide visual and audible advice using HoloLens’s mixed reality capabilities. These remote subject matter experts can see what onsite technicians see in real time and even draw visual indicators on the technician’s field of view to assist with repairs. By adding HoloLens to their solution, thyssenkrupp has set a new standard in elevator innovation, reducing the average length of its service calls by up to four times.”

From: Microsoft Azure IoT Suite and HoloLens enable revolutionary solutions for thyssenkrupp Elevator

“Technicians can be hands free while on the job, even when making remote calls to subject-matter experts and sharing holographic instructions between users. This enables more flexibility while also complying with safety regulations. In initial trials, use of HoloLens has reduced the average length of thyssenkrupp’s service calls by 4X.”
From Microsoft HoloLens enables thyssenkrupp to transform the global elevator industry

“We tried many, but this is the technology we chose. It’s easier to apply and really easy to model,” Schierenbeck says. “You have a completely open image of the reality in front of you and all the data you want to access in your vision area.”

From: Quicker fixes, hands-free, when thyssenkrupp Elevator’s service technicians use Microsoft HoloLens

Towards content lakes

One of the trends in both data and content management is the move away from silos. In data management circles, there is a trend towards the collection and aggregation of customer data into “data lakes”. According to Margaret Rouse, a data lake is:

A storage repository that holds a vast amount of raw data in its native format until it is needed. While a hierarchical data warehouse stores data in files or folders, a data lake uses a flat architecture to store data. Each data element in a lake is assigned a unique identifier and tagged with a set of extended metadata tags. When a business question arises, the data lake can be queried for relevant data, and that smaller set of data can then be analyzed to help answer the question…Like big data, the term data lake is sometimes disparaged as being simply a marketing label for a product that supports Hadoop. Increasingly, however, the term is being accepted as a way to describe any large data pool in which the schema and data requirements are not defined until the data is queried.

(source: what is a data lake?)

“Content lake” isn’t a word that’s used in the content management or technical communication sectors yet, and whilst it seems unlikely end user content will grow at the same rate as other forms of data, there’s a fair chance this phrase could catch on.

A content lake is likely to have similar attributes to a data lake:

  • Content will be stored in a native format that is then changed into other formats.
  • It will use a flat architecture to store data.
  • Content will be stored in some type of structured format. Perhaps XML, JSON or plain text (with AsciiDoc-like attributes assigned to certain sections). However, user documentation does not require the rigorous structure of other forms of content.
  • The content lake can be queried for relevant content, and that a smaller set of information can then be extracted to help answer questions. This might not mean publishing content on-the-fly, but generating PDFs, CHM files and web-based content from a single source.
  • Rather than content being simply archived, it will deliver the right information in very short timeframes.

See also:

Please share your comments below.

Documentation as Code

Tom Johnson has written two interesting posts on his blog on the “Documentation as Code” concept:

Documentation as Code can be interpreted in a few ways. Tom describes it as being able to store the documentation with the code:

From a technical angle, Etter argues that one should embrace lightweight markup languages, use static site generators, and store content in version control repositories with engineering code.

An other interpretation associated with this is that documentation should be seen as a design problem; it should be seen as part of the product (and seen in a similar way to the software code), rather than an add-on. If the documentation is stored with the code, it can mean that the requirements for documentation can be more closely linked to the code. When a requirement for a new feature is raised, so can a requirement for the related documentation. It can also mean that content that’s embedded in the UI, presented as on-boarding screens or presented as online Help, can be considered as different potential solutions to each user need.

Documentation as Code is a topic we touch on in our advanced technical writing training course. It’s an approach that we may see growing in popularity.