Documentation as an API – the docsbot

In a recent presentation, Twilio’s Jarod Reyes and Andrew Baker mentioned their plans to make Twilio’s developer documentation available as an API. They plan to start with an API for code samples, stored in a github repository.

Making documentation available as an API means means users can create or remix their own versions of the documentation. For example, they could embed Twilio’s code samples. It also means those embedded code samples will be updated whenever Twilio updates those snippets of code.

Jarod and Andrew suggested something new that we’d not heard before – the API can also be used to create a “bot” in Slack, to help new users. The Twilio bot, currently in development, is called docsbot. If users type “lookup py” in the Slack command line, docsbot will reply with a message containing a code sample for the Python development environment.

Twilio's Slack docsbot

It relies on users knowing the relevant Slack commands, but it’s an interesting way of providing users with documentation when and where they need it.

See also: Advanced technical writing & new trends in technical communication training course 20th October

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.

Americanisms and Britishisms

There are user documentation projects where we are asked to write in American English instead of British English, and generally this is a pretty straightforward exercise for us. However, when I speak at conferences in the USA, delegates sometimes ask me afterwards what I meant by a particular expression. For example, I was recently asked what I meant by “round the houses” and “cheesed off“.

There are a large number of subtle differences between the two versions of English, which has led to a number of very interesting blogs on this subject. In particular, Dr. Lynne Murphy’s Separated by a common language and Professor Ben Yagoda’s Not One-Off Britishisms blogs provide a fascinating insight into how words and expressions gain popularity. The Language Log is another blog worth reading.

If the move to a more conversational approach to technical writing grows in popularity, we may see these differences becoming a bigger factor in localis(z)ing to American or British English.

The next advanced technical writing course will be on 23rd June

The next public Advanced technical writing & new trends in technical communication classroom course will be held on Thursday 23rd June, at our training centre in central London (WC2R). We’ll be updating the content from last month’s course, to reflect the recent and upcoming developments at Microsoft.

Microsoft launches its new documentation site, and it’s very good

Microsoft has announced the preview release of its documentation service,, which currently provides content for its Enterprise Mobility products.

“We interviewed and surveyed hundreds of developers and IT Pros and sifted through your website feedback over the years on UserVoice. It was clear we needed to make a change and create a modern web experience for content…For years customers have told us to go beyond walls of text with feature-level content and help them implement solutions to their business problems.” (source)

The key features are:

  • Improved readability
    • “To improve content readability, we changed the site to have a set content width.”
    • “We’ve also increased the font size for the left navigation and the text itself.”
  • Including an estimated reading time
  • Adding a publication date
  • Improved navigation
    • It is now based around sections on evaluating, getting started, planning, deploying, managing and troubleshooting
  • Shortened article length per page
  • Responsive Web Design
  • Community contributions
    • “Every article has an Edit button that takes you to the source Markdown file in GitHub, where you can easily submit a pull request to fix or improve content.”
  • Feedback mechanisms
    • To provide comments and annotations on all of the articles
  • Friendly URLs
  • Website theming
    • You can change between a light and dark theme

Wow – this matches closely with the topics we cover in our Advanced technical writing & new trends in technical communication training course, where we look at the changes made by other organisations.

Although it doesn’t mention it in its announcement, Microsoft has also made changes to the style of its topic headings and content. There’s frequent use of words and phrases such as “protect”, “discover” and “understand and explore”.

We’ve yet to look at the site in detail, but initial impressions are very positive.

What do you think?

The return of Clippy?

Are we seeing the the spiritual child of Clippy emerge? Truth Labs’s Stelios Constantinides has written an article on his experiments with conversational UIs.

Conversational user interfaces (CUIs) are a spoken or written way of interacting with a device. CUIs aren’t completely new, but they’re becoming smarter, more natural, and — therefore — more useful.

Here’s where CUIs come in: since users already spend so much time in apps like Slack, Facebook Messenger, and even plain-old email, why not integrate your app inside these platforms?

Microsoft ClippyConstantinides  looks at the design process of creating something that doesn’t come across as a robot, and isn’t as annoying as Microsoft Clippy.

This links in with Ann Rockley’s concept of Intelligent Content: “Content that’s structurally rich and semantically categorized and therefore automatically discoverable, reusable, reconfigurable, and adaptable.”

For conversational user interfaces to work well, they need to be automatically discoverable, adaptable and semantically categorized. Microsoft Clippy wasn’t, which is one of the reasons why it failed in its purpose.

It’s still unclear whether this will lead to content being seen as code, or stored in a semantically rich format and inside a content management system. Whichever way, it’s important to recognize that the conversational language is different from written language. We speak differently from the way we write, and this is reflected in how we use messaging apps and authoring tools. Conversations are typically a one-to-one form of communication.

With Siri, Google Voice and Cortana closed off to most developers, we’re likely to see conversational user interfaces developed as alternatives to these applications.

One school of thought is users will move away from searching using sentences, and, instead,  learn to type commands (they will write command line instructions). In other words, they will begin to think and type more like programmers. This is illustrated in the image below.

Slack command line

I wonder if this might be a bit optimistic. There are many people find Twitter too difficult to use, and I suspect it would take them a long time to adapt to this approach.

This topic is something we cover (albeit briefly) in our Advanced technical writing & new trends in technical communication training course (the next one of which is on the 22nd of March).

See also:

(With thanks to Simon Bostock)

What do you think? Share your thoughts using the comment box below.