The T-Bot: A new Help model from Microsoft

This month, Microsoft has added Microsoft Teams to Office 365. It’s a instant messaging collaboration tool, similar to Slack. Teams contains the T-Bot, which provides help and assistance to users.

T-Bot main screen

Users can watch videos:

T-Bot Help videos

They can read online Help:

T-Bot online Help

They can read an FAQ:

T-Bot FAQ

They can ask the T-Bot a question and receive an answer. The T-Bot initially provides the same answers as the FAQ. If it doesn’t know the answer, it will suggest some articles from the Help:

:T-Bot Question and Answer

Do you think this way of helping users is good? Share your thoughts, using the comments form below.

GDS publishes its new design for technical documentation

The Government Digital Service has been working on establishing a standard design for its technical (i.e. developer) documentation. This content is for systems architects, developers and users of the GOV.UK platforms and APIs.

You can see an example at: GOV.UK Platform as a Service

Gov.uk technical documentation

Cherryleaf was given a preview of the new design a few months ago, when we ran an API documentation training course at GDS. We made a couple of suggestions, which look like they’ve been included in the final design.

The documentation has these main sections:

  1. Overview. This includes why you would use it, and the pricing plan.
  2. Getting started. This includes prerequisites and limitations.
  3. How to deploy
  4. Troubleshooting
  5. Managing apps
  6. Managing people

Elsewhere on the website is information relating to support, the product features, and the product roadmap.

As with other GOV.UK content, the team carried out research into what developers wanted, and they carried out usability testing. I understand the researchers discovered developers preferred content to be on a long, single page, and that they would be working in a two screen environment. Using long pages enables users to search and navigate with the keyboard, rather than the mouse. GDS also looked at other developer websites, such as WorldPay and Stripe, for best practice.

GDS is highly regarded in the technical communications community for its excellent work on the GOV.UK website. This means it is likely other organisations will copy GDS’s design for their own developer documentation.

 

March dates: Advanced technical writing and new trends in technical communication training course

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.

The next public classroom course will be held on Wednesday 29th March 2017 at our training centre in central London (WC2R).

For overseas clients, we will hold a class live over the web (on 22nd and 23rd March), if there sufficient interest.

See:

Advanced technical writing & new trends in technical communication training

 

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