Transcript of Delivering technical documentation via an API

Below is a transcript of our podcast episode Delivering technical documentation via an API:

Welcome to the Cherryleaf podcast. In this episode, we’re going to look at documentation APIs.

In a previous podcast we looked at trends in technical communication, and we were debating whether to include documentation via an API as one of the future trends for 2018 and beyond.

We thought we’d explore it in a standalone episode, which is the episode that we have here. So we’re going to look at: What is a documentation API? Why you might want to use one some examples, and some of the tools and platforms that are currently available.

One of the challenges with this topic is there are actually a lot of content APIs around, and a lot of the information that’s transferred is content.

  • You have APIs for providing weather information: that the weather in a particular city is so many degrees, and it’s windy, or it’s cloudy.
  • And we have APIs for adverts. So there’s an API for Bing, where you can use that to get different adverts embedded onto a particular sites.
  • And there’s also APIs for platforms provided by organizations like the BBC and the Guardian,

And often this information is organized in pairs of data; a key and then a value for that data, stored in a text file, usually in a format called JSON. And in many ways this is what you might have previously called just “data”.

So we need to try and differentiate what we mean by documentation from that type of information. Differentiate the type of information and content that technical communicators provide. The type of information that you would see more in a instructional set of guides than in a weather report.

The definition that we’re going to use, or the focus that we’re going to take, is on the type of information that you might see in a user guide or an online help file, and that essentially is instructional, task based information, or reference, look up, information, and particular information that might be more than just a city and the temperature. So content that might need to be presented in tables, for example.

And again another challenge with this topic that can make it rather confusing is, of course, a lot of this can also be delivered if you wanted to automate it. And that’s one of the reasons why you’d use an API. You could automate it by using a chatbot, where that would be serving up the information, and potentially providing that information using voice rather than text, and we’ve done a podcast on chatbots previously; so we’ll leave that for this episode. Have a listen to our podcast on chatbots. We’ve also got a primer guide to chatbots as well, so do have a look at that.

So why would we want to use an API to deliver documentation? We can use a content management system today to deliver information. It will enable us to deliver it as web pages, as self-contained Help files, as PDFs, and a content management system can personalize content. It can narrow and filter the information to suit different users, individual users.

So what would an API give us over and above what we can use today with the content management system? To answer that question, a good starting point is to go back to what an API is. And in its simplest terms, an API, an application programming interface, is a way that two machines, or two pieces of software, can talk to each other automatically.

The use case or the situation where we might want to use an API is where we want our content to be used by another system. So that may be where there is a system that has a workflow and there is a need to provide the end-users with information and make decisions. A performance support role for the content. A number of examples of this might be that you have Salesforce.com as your platform for supporting end-users, for marketing and selling in your company, and you may have customized and adapted Salesforce to your particular situation; included the different products that you offer, the different prices, different types of customers, and so on, and you might want to provide specific information to your Support people or to your salespeople that can have on the page, as they’re going through a support call or a sales call, information from the instructional content, from the reference content, from what might have been in the past called a user guide.

Another example is one that was mentioned on another podcast, Scriptorium’s podcast, a case study on how they have worked with the American Joint Committee on Cancer. The AJCC provides a manual on cancer staging, related to whether somebody has Stage 1, Stage 2, Stage 3, Stage 4 cancer, and that information is used by providers of medical systems to help doctors make decisions. And the AJCC has converted that content into being an API, so that these providers of healthcare management systems can include this official content on what is defined by different stages and how you would make decisions to classify a patient. Having one of those, they made that information available as an API, so that the software providers can include it in there. And we will include a link to that podcast, that Scriptorium podcast, in the show notes.

Another situation may be that you’re using a platform like SAP, and that you have customized the SAP platform for your particular situation. So that it’s organized by the number of offices, or the number of factories that you have, or again the number of products. And to help somebody that’s perhaps defining the levels of depreciation in different countries for depreciating assets, or making decisions over a stock rotation, there is reference information in your system. Legal information they might need to be aware of company policies. Do’s and don’ts that that could be embedded into the SAP screens from an API.

So a common theme may well be that you want your information embedded into other applications. You might want information that describes different parameters as to when and where you’d make a decision. Issues around safety; it might be rail safety, it might be aircraft safety. Making sure staff conform to certain rules. Those are some scenarios where API delivered content might be useful. How can we use an API to deliver our content? Well, one approach is to use one of the platforms that’s used for content. A platform, for example, like a content API platform. If we’re using voice, we could look at the APIs that Amazon provides. And one of the ways in which Alexa is being used, is to provide instructions and information on recipes, or instructions on how to use a product.

But again we’re we’re veering into chatbots. Let’s move away from that.

Another platform might be the GatherContent API, which will interact with a number of systems. In particular, platforms that provide help desk type information. The team that have developed the ReadTheDoc’s platform for API developer documentation has a platform called EmbedAPI. And this enables you to embed content from your content if it’s on the Readthedocs website. And enables you to embed that content that’s hosted there into other platforms. And this is a way of making sure that’s API related documentation, which is often the type of content that resides on Readthedocs, is always up to date always there in these other applications.

What about platforms within the field of technical documentation more focused on user based instructional content? What do we have in that way?

Well, there are a few, but but not many at this stage. There is Paligo, and Paligo is a content management system in the cloud, and is based on DocBook. The content is structured in that way, and it’s possible to use the Paligo platform and its API, to have your content integrated with some of the most common help desk portals and with Salesforce.com. Mindtouch, which is a popular platform browser-based platform, again for providing help desk information and also user instructional information, that also comes with an API. And you can use the Mindtouch API to extend your product documentation so it’s included throughout the customer journey.

If you’re using Markdown to write your content, your choices are going to be more limited. Because there is this need to have this semantic wrapper around this content, this metadata, to say what information is there is. One platform that can do that, one called Forestry. The API for that is not publicly available, but there is a private API that’s available on request. So that may be worth considering if you want to write only using Markdown.

So that’s a very brief overview. We have these overlaps between other API systems that provide other types of content. We have overlaps with chatbots and voice based information. And it may be that documentation is API won’t really become distinct from those. But there may be, in the future, a need to distinguish like we have between those other forms, and provide our content via an API into other systems. It really depends if your content needs to be used by another system, if you need that situation of one machine talking to another.

We’d welcome your thoughts and your experiences on using documentation based APIs, and other content APIs, where they’ve been applied to technical documentation. So do share your thoughts. We have interviewed people in the past on the podcast, so there may be an opportunity to record some of your thoughts.

If you’d like to contact us, you can email us: info at cheryleaf.com.

If you want to see these show notes, with links to some of the topics that we’ve talked about, some of the products, you’ll find those at cherryleaf.podbean.com.

And if you’d like to know more about Cherryleaf, and our documentation services, the training courses, the recruitment side, and the project side, then you’ll find that on our website Cherryleaf.com.

So this is the last podcast episode for 2017. We wish you a happy New Year, and we’ll be talking to you again by podcast, and through other means, in 2018. Thanks for listening.

Incorporating the Stripe API look and feel into a MadCap Flare project

Back in July, we looked at creating an API documentation portal using MadCap Flare (see also: Example of API documentation portal using MadCap Flare) .

We done some further testing. We’ve created two new examples for  API documentation that had been generated with the Stripe API look and feel and imported into Flare:

To compare the two, here is the standard “Stripe API” left-hand Table of Contents when imported into Flare.

We’ve not made any changes to the default Heading styles from the source files. The stylesheets would needed to be modified to make them consistent with the styles used on the other HTML pages in the project.

Docs Like Code – Interview with Anne Gentle

Here is early access to the latest episode on the Cherryleaf Podcast – Interview with Anne Gentle, author of Docs Like Code and Product Manager at Cisco. It will be published on the podcast channel on Monday.

Topics covered:

  • What is docs as code?
  • Why do it?
  • When might this approach might be applicable?
  • The limitations
  • Docs like code in development sprints
  • Is it only for developer docs?
  • Do you you need to understand programming?
  • Why did you self publish?
  • The benefits of taking this approach
  • The future developments
  • Automating document builds

Links to topics mentioned:

Subscribe to Cherryleaf’s newsletter

Cherryleaf training course – Advanced technical writing techniques

https://www.docslikecode.com/

Conversation and Community: The Social Web for Documentation

Troy Howard Documentarian, Super Genius at Twitter

http://codewerdz.org/ Repository analytics for code and docs

Matt Fleming on Twitter

Docs Like Code GitHub repository

Jekyll

https://docs.openstack.org/pike/

WADL RAML OpenAPI

https://bitbucket.org/

http://docs.metacloud.com/

Liquid scripting

YAML

PrinceXML

Lunr Search Engine

Solr (Search Engine)

Why we use a ‘docs as code’ approach for technical documentation Jen Lambourne, GDS, GOV.UK

The Definition of Done

Learn Python the Hard Way

AsciiDoc

ReST

GitHub Flavoured Markdown spec

XML Press

REST API

Building Docs Like Code – article

Travis CI 

Jenkins

Circle CI

Webhooks

Bash scripts

An Introduction to Static Site Generators

GitHub Pages 

Example project – API documentation portal using MadCap Flare

Note: This post follows on from two previous posts on creating a unified API documentation portal:

We’ve just uploaded an example project of an API documentation portal created using MadCap Flare:

The documentation portal includes API reference documentation that was generated automatically from a Swagger/OpenAPI specification file.

Whenever the REST API specification is updated, that content automatically updates itself in the Flare project.

Using MadCap Flare means you can provide a consistent user experience: for the reference, troubleshooting, getting started and tutorial content. Flare also manage the content, search, linking, pdfs, tables, flowcharts etc.

The steps are:

  1. Generate the API reference documentation in HTML format from the OpenAPI specification file. This could be generated automatically each day.
  2. Import the API reference HTML file into Flare. Select Link Generated Files to Source Files. This creates a connection between the original HTML files and the files that are created as a result of the import. Flare recognises when changes have been made to the source documents.
  3. Fix any initial CSS issues. The API reference HTML file links to a cascading stylesheet file. We found we needed to create a CSS file with the same name, as there were some issues with displaying the top navigation menu bar.
  4. Generate and publish your web site. You can run Flare’s “Build” command from the operating system’s command line. This means you can create a batch file with the necessary commands in it. Then you can use a scheduling tool to run the batch file automatically.

Further work could be done to improve the outputs:

  • We’ve not made any changes to the default styles for the PDF manual.
  • Amending the cascading stylesheet for the Stripe-style API documentation
  • Adding code samples.

See also: Cherryleaf’s API documentation writing services

Example of API documentation portal using MadCap Flare

This post follows on from our Creating an API documentation portal with MadCap Flare and Swagger/OpenAPI post. It shows screenshots of a test project we created. We used Swagger’s “petstore” example API specification as the source content. We didn’t spend any time modifying the stylesheets – these are just proofs of concept.

API documentation Home page

All the content uses the same navigation, and look and feel:

API documentation example in MadCap Flare - Home page

API reference information – single page

In this example, all the reference information is stored in a single file. We set the Flare project up in a way that this content updates automatically whenever the API specification file changes. There’s more work required on the stylesheet and Flare master pages in order to improve the look and feel.

API documentation example in MadCap Flare - Single reference page

API reference information – multiple pages

In this example, all the reference information is split into a multiple files. We set the Flare project up in a way that this content updates automatically whenever the API specification file changes. There’s more work required on the stylesheet and Flare master pages in order to improve the look and feel.

API documentation example in MadCap Flare - split into multiple pages

API reference information – resources and endpoints

API documentation example in MadCap Flare - post example

API documentation example in MadCap Flare - resource example

Incorporating content created by developers in Markdown

This shows an example of content created by a developer in Markdown format and imported into the project. This means the developers wouldn’t have to use Flare for any of their contributions, if they didn’t want to.

API documentation example in MadCap Flare - Markdown import

The advantage of this approach is it would give users a coherent and consistent user experience across all the API documentation.

See also: Cherryleaf’s API documentation writing services.

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.