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.

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.

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.

SankeyTextualVariant: Visualisation software for comparing texts

Professor Martin Paul Eve of Birkbeck College, University of London, has released, for free, the visualisation software that helped him compare the texts of the novel Cloud Atlas. It displays the differences as a Sankey diagram. It’s intended to be used for comparing contemporary fiction, but it may have uses for analysing other long documents.

sankeydiagram

See:

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.

General Data Protection Regulation – will this affect online Help?

Yesterday, I saw a presentation by Hazel Southwell on the EU’s General Data Protection Regulation (GDPR), which will be implemented on the 25th May 2018. The impact in its data privacy and protection rules seem likely to affect pretty much every website, with the threat of hefty fines for those that do not comply.

Organisations providing personalised Help content, by storing information in cookies or monitoring the behaviour of users living in the EU by tracking their digital activities, will need to comply with the GDPR regulations. In particular:

  • Businesses will have to adopt governance and accountability standards and meet their data privacy obligations.
  • Clear and affirmative consent to the processing of private data must be provided, and the relevant information must be laid out in simple terms.
  • Organisations need to consider the risks of transferring data (such as the storing of cookies or IP addresses) to countries outside of the EU.

One solution is to require users to log in to see information. However, this may be an unpopular and impractical solution for many users.