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:


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.

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.



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.