Creating an API documentation portal with MadCap Flare and Swagger/OpenAPI

MadCap Software has published a whitepaper called The Definitive Guide to Creating API Documentation. It covers ten best practices for writers, and it describes how you can use MadCap Flare to implement these when you are writing API documentation. In this post, we’ll look at whether we can combine automatically generated REST API reference documentation with Flare, to create a web site that gives users a coherent and comprehensive user experience.

When writing REST API documentation, a lot of organisations use the API reference documentation that can be generated automatically from an API specification. Tools like Swagger UI can create web pages, which you can publish to a website.

The downside of this approach is the automatically generated REST API reference documentation typically has its own look and feel, and navigation structure. To the user, it often looks like there are two separate sites. One contains the reference information. The other describes what the API does, why you’d use it, how to get started, how to get an authentication key, how to get a “Hello World” response, tutorials, and so on. As soon as a website’s look and feel changes, there’s a cognitive load on the reader. They need to assimilate what has changed. It’s like trying to complete a task with two manuals open at the same time.

As a side project, we are looking at how you can create a site that has a cohesive set of documentation. In other words, make it easy for the user to move back forth between the automatically generated REST API reference information and other REST API documentation. You can do this with static site generators, but these often have limitations. By using MadCap Flare, you can include a site search, manage multiple versions, manage pro/lite products, re-use content, publish to PDF, manage localised content, manage synonyms, and avoid inserting scripts into pages that only the original creator understands. MadCap Flare is good at scale, dealing with the messier problems that often affect documentation.

The objectives are:

  • Include REST API reference content automatically generated from the API specification. Whenever the REST API specification is updated, that content automatically updates itself in the Flare project
  • Include content written by developers in Markdown. In other words, let the developers write in their preferred authoring environment. If a developer updates that content, that content automatically updates itself in the Flare project.
  • Use Flare to manage the content, and do the messy stuff like search, linking, pdfs, tables, flowcharts etc.
  • Publish web pages that provide a comprehensive and coherent user experience.

Can this be done? Yes. The main issue is whether to keep all the automatically generated REST API reference documentation as a single web page, or split each resource into separate topics (i.e. separate web pages). We’re currently looking at the best way to do both. When we’ve settled on the best approach, we’ll publish some examples on the Cherryleaf blog.

Take part in the Cherryleaf 2017 European salary survey

It’s been a while since our last survey of technical communicator salaries. So we thought it was time we conducted a new one.

We have contracted with QuestionPro, an independent research firm, to field your confidential survey responses. All responses will remain confidential and secure.

The questions will help us learn if salary levels correlate to factors such as age, gender, education, or levels of seniority.

We’ll publish the results on this blog.

Please use this link to complete the online survey:

Take part in the Cherryleaf 2017 European salary survey

Help through AI, Help like Facebook

Reviews of two presentations at the UAEurope 17 conference.

Kristof Van Tomme (Pronovix). Software support and Artificial Intelligence.

Pawel Kowaluk (3di Poland). Knowledge Feed: Make your Online Help More Like Facebook

Interspersed with interviews from at the UAEurope 2017 conference:

Dr Tony Self. HyperWrite

Willam van Weelden. Adobe

Mike Hamilton. MadCap Software.

Is your documentation AI and chatbot ready?

It seems likely Artificial Intelligence (AI) and chatbots will play a key role in helping users, in the future. Amazon, Facebook, Google, IBM and Microsoft, as well as smaller technology companies, are all developing platforms for simulating an intelligent conversation with human users.

This raises a question:

Will chatbots mean we’ll write a how-to task in the chatbot app, again in the Help, and again in the tutorials?

It’s not very productive to write the same content three times, in three different places. It makes even less sense if you need to update the content on a regular basis, or translate that repeated content into multiple languages.

One solution is to store different types of data in its native format until it is needed, and then serve that information to the AI or chatbot system. You write the content once, and “serve” it to the chatbot, the online Help, the tutorial, and so on.

This requires that content to map accurately to the chatbot’s information structure  –  the use cases; the user’s intent, role and sentiment; and the entity (i.e. the problem and product) that relates to the user’s question.

As a technical communicator, this means you can start by making sure your content is in a structured format. For example, it has metadata (and uses a taxonomy) that will help the AI system or chatbot know which piece of information to serve the user. This includes common metadata such as product, symptom, problem, version, user role and operating system. It may also include new metadata relating to responses based on the user’s current mood (“sentiment”),  and the context in which the question is made to the chatbot.

This approach makes it more likely that your documentation will AI and chatbot ready, at the time when it’s needed.


Tryo Labs has published a useful summary of the different approaches and technologies you can use for creating chatbots. See: Building a Chatbot: analysis & limitations of modern platforms.

See also:

Towards content lakes

Cherryleaf’s technical writing services

The ROI of user documentation: you could break even if you avoided 3 support calls per week 

We’ve been experimenting with another spreadsheet for calculating the Return on Investment (ROI) on User Assistance.

We wanted to look at: how many support calls an organisation needs to have resolved by users reading the Help content instead of calling Support, before it starts to see a return on the cost of creating the Help.

Using typical costs for an average sized software application, the figures suggest you could break even if you avoided 3 support calls per week.

Chart showing the ROI of user documentation

Contact us if you’d like a copy of the spreadsheet, so you can make your own calculations.

You also find a related Support call cost reduction spreadsheet on the main Cherryleaf website.

Every Page is Page One – Interview with Mark Baker at UAEurope 2017

Here is an interview we carried out with Mark Baker, author of Every Page is Page One. The interview is interspersed with audio snippets from Day 1 of the UAEurope 2017 conference.

Presentations:

  • Caroline Loverage (Thermo Fisher Scientific). Teaching by Example: Worked Examples in the Documentation of Complex Systems
  • Kelly O’Brien (Kayako). Practical Information Architecture: Building Templates For Better Content.
  • Helena Pichler (Nominet). AsciiDoc to Responsive Webhelp: Agile documentation for small teams/

With thanks to Matthew Ellison and Mark Baker.

Goatskin single sourcing

The content management and single sourcing challenges for the UK Parliament:

However, all is not quite what it seems:

“Just when you thought Goatgate had been cleared up, along comes the official line: It is not on vellum anymore. It is on “goatskin parchment paper” but confusingly it’s not actually goatskin. However it is very high quality, thick paper, which is why the ink takes several days to dry, and it then needs to be bound into a booklet, before being sent on to Her Majesty for signing. So it did have to go to the printers last week. And the paper does have the watermark of a goat”

See: How the Queen’s Speech got my goat.