About Ellis Pratt

Ellis Pratt is Sales and Marketing Director at Cherryleaf. You can follow Ellis on Twitter. Cherryleaf helps you provide technical and user documentation your customers will love - through our content development, recruitment, consultancy and training services. See the main Cherryleaf web site for more details.

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

Customer Journey Mapping and technical communication

A technical communicator’s lot is usually to create content for helping users, and, if they are lucky, do some user testing of it in order to make future improvements. It is not that common for them to be able to look at the bigger picture and think about how the user gets to that information in the first place.

Customer Journey Mapping is an extremely useful way to understand and improve the customer experience. It involves creating a document (often a spreadsheet) that describes the user experience from their perspective. It can record each point at which interact with your service or product, the quality of that experience, and what happens next.

Customer Journey Mapping is something we carried out recently for a client, and it was a topic that came up at the TCUK 2016 conference, in the presentations by both Sarah Richards and Simon Anstey.

Our client is a start up Software as a Service company that is growing rapidly. They are creating new products, gaining new customers, and they are having to face all the challenges that brings. We mapped the journey of a user who wanted to install the product. We used a spreadsheet to record each stage and any issues or problems that users came across. The user began at the company’s website, where there were various links for installing the application, including instructions on how to do that. It revealed there was confusion between the product available on Amazon Web Services and the product clients install in-house. This was because the same, or similar, terms were used to describe the products themselves and the features contained within the products. On some pages, users were directed to the Support desk system and the articles contained there. On other pages, they were directed to PDFs, which described how to install the previous version of the product. There were also a few pages that took them to the online Help system. The Customer Journey map made it easy to change the website so it directs users to the single place for information, and to remove duplicate, and out of date, information.

In Sarah Richards’s presentation at TCUK 2016, she described the approach the Government Digital Service took when they developed the Gov.uk. website. GDS removed content that didn’t address those needs, and consolidated hundreds of government websites into the single gov.uk site. They kept 45,000 pages, and culled 92,000. This process started with user needs, and were designed around those customer journeys.

Sarah’s TCUK 2016 slides aren’t available yet, but here is a similar presentation she gave at another conference:


 

In Simon Anstey’s (of SAP) presentation, on eliminating Support tickets, he described how he looked at the customer journey for raising a Support ticket, and collaborated with SAP’s customer support team to improve the documentation, and links to useful information, for some critical products. This stemmed the flow of support tickets. They estimated the resultant cost savings and started gaining management’s interest. This activity meant they could show what value documentation was adding.

Customer Journey Mapping can be revelatory in revealing issues that may not be obvious at first glance.

Research into how API documentation fails

There isn’t a great deal of research into API documentation, and the factors that make API content good or bad. Here’s some of the papers we’ve found so far:

How API documentation fails

How API documentation can be effective and useful

Do you know of any others?

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.

Hyperbaton and the unwritten law of order of adjectives in English

Mark Forsyth’s description of hyperbaton (putting words in an odd order) in his book “The Elements of Eloquence” is the subject of a tweet that is currently trending on Twitter:

“opinion-size-age-shape-color-origin-material-purpose”

See also: Making Rhetoric Relevant

New online MSc in Technical Writing

The Department of Computing at Cork Institute of Technology (CIT) has announced new online Masters degree in Information Design & Development for 2016-17, together with a certificate and a postgraduate diploma. There aren’t any undergraduate or postgraduate university courses in the UK for technical communication, so online courses in other countries can be an alternative solution.

In comparison to the technical writing training courses companies such as Cherryleaf offers, a Masters course should offer a considerable amount of academic rigour. Our courses are focused on the functional skills of doing the work of a Technical Communicator, whereas a university course should make you think about the theories and assumptions that underpin technical writing theory and best practices.

The course outlines for the three courses that CIT offers look quite good. The certificate covers Information Strategy, Information Design & Development, Multimedia Production, and XML in Technical Communication. The postgraduate diploma adds Human Information Interaction, Document Project Management and Emerging Technological Trends, plus an elective module (Information Analytics, Scripting for System Admins, or a free choice of other modules). The elective modules aren’t directly relevant to technical communication (particularly the one on scripting), but sometimes there can be value in looking outside a field for ideas. For the MSc, you conduct a research project.

Surprisingly, there doesn’t seem to be much on e-learning, the Write the Docs movement, API documentation or localisation. I also wonder if there’s much investigation into the sturdiness of the long-standing theories of technical communication.

The four semester, 18 month, Masters course costs €6,300; the postgraduate diploma course costs €4,200; and the certificate course costs €2,100.