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

GDS publishes its new design for technical documentation

The Government Digital Service has been working on establishing a standard design for its technical (i.e. developer) documentation. This content is for systems architects, developers and users of the GOV.UK platforms and APIs.

You can see an example at: GOV.UK Platform as a Service

Gov.uk technical documentation

Cherryleaf was given a preview of the new design a few months ago, when we ran an API documentation training course at GDS. We made a couple of suggestions, which look like they’ve been included in the final design.

The documentation has these main sections:

  1. Overview. This includes why you would use it, and the pricing plan.
  2. Getting started. This includes prerequisites and limitations.
  3. How to deploy
  4. Troubleshooting
  5. Managing apps
  6. Managing people

Elsewhere on the website is information relating to support, the product features, and the product roadmap.

As with other GOV.UK content, the team carried out research into what developers wanted, and they carried out usability testing. I understand the researchers discovered developers preferred content to be on a long, single page, and that they would be working in a two screen environment. Using long pages enables users to search and navigate with the keyboard, rather than the mouse. GDS also looked at other developer websites, such as WorldPay and Stripe, for best practice.

GDS is highly regarded in the technical communications community for its excellent work on the GOV.UK website. This means it is likely other organisations will copy GDS’s design for their own developer documentation.

 

Policies and procedures as an API

Here’s a trend that didn’t make our list of predictions for 2017 – having company policies and procedures accessible via an Application Programming Interface (API).

API is a term used to describe mechanisms that allow an application to access data or functionality provided by another application, system or service. For example, if your policies and procedures were accessible via an API, they could be embedded or used in other systems within your organisation. APIs offer connectivity, flexibility and future-proofing.

Instead of staff having to look up procedures in a manual or on an intranet, the official guidance or instructions could be embedded into the applications and forms they’re using. Developers could save time by connecting the application they’re developing to the API. They wouldn’t need to write the information, and staff would always be presented with the official, definitive policy or procedure.

You’re still able to create policy and procedure documents, as a web page or in paper format.

This prediction didn’t make the list because it relates mostly to business documentation rather than technical documentation, and we’re unlikely to see many examples of it within the next 12 months. In practice, the content might be managed by a headless CMS; however, the approach would remain the same. Perhaps the NHS and other organisations in the healthcare sector will be the first to take of this approach.

See also: Cherryeaf’s policies and procedures writing services

What do you think of this prediction? Please share your thoughts below.

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

Microsoft publishes its REST API Design Guidelines

Microsoft has published  its REST API Design Guidelines to the API community.

Microsoft API guidelines sample

According to Gareth Jones, Principal API Architect, who announced its release:

“The effort got started from hearing two key points of feedback from customers:

It should be easier to get started with Microsoft APIs – Developers wanted to be able to run the curl tool against an API endpoint and get a human-readable result in just a few minutes

APIs for Microsoft cloud services should be consistent – Developers didn’t care that an API to work with an Azure virtual machine and an API to work with a user’s Office 365 documents were developed by different parts of the company, they were both from Microsoft and developers expected consistency

One of the goals of the effort was to find the right balance of detail in the guidelines. We wanted a document that sufficiently codified best practices, but was also approachable for individual contributor engineers and technical product/program managers.”

Microsoft is a member Open API Initiative, which has been spun out of Swagger.

According to Gareth Jones:

“These guidelines represent a multi-year, cross-company, collaborative process aggregating the collective experience of hundreds of engineers designing, operating, and running global scale cloud services from across Microsoft; and listening to feedback on our APIs from customers and partners.  We have attempted to incorporate those learnings along with industry best practices in the API space to create guidelines that API teams across Microsoft use on a daily basis.”

“It’s our hope that by contributing ours to the community conversation, we can add to the body of community knowledge and reusable content so that anyone can draw upon more collective knowledge when looking to set standards and guidelines within their organization.”

Links:

Lessons learnt from developing our API documentation course

We’ve written our new training course on documenting APIs, bar the model answers, and it’s now out for review. We’ve learnt a few lessons, and confirmed a few beliefs, whilst developing the course. We thought we’d share them below:

  • Start with the absolute basics. It’s best to assume little or no knowledge of the subject, and start from there. It’s easier to skip or omit those sections, than try to add them in at a later stage.
  • Stick with a single theme for the exercises and examples. One of the challenges we had was to create exercises and examples that take delegates through all the stages of developing API documentation. We decided to base these on an imaginary API for a hospital, and this turned out to be a good choice. It’s meant we can use real world examples from healthcare,  as well as ones we’ve created, during the course.
  • Make the examples visceral. The more you can anchor the exercises into people’s lives and experiences, the more real and meaningful they will be for them.
  • Don’t get sucked into looking at only one tool. There are a number of ways to develop API documentation, and the tools are developing at a rapid pace.
  • Don’t be too ambitious with the exercises.
  • Writers want to write on a training course about documentation, so give them the opportunity to do so.
  • Set realistic expectations regarding coding skills. You can’t teach people how to code in multiple languages in a day, so you need to provide building blocks that they can build upon in the future.

The slide deck now comprises 330 slides, and the test recordings indicate it’s a one day course. We’re still not convinced we have the best title for the course – if you have any suggestions, do let us know.

New course – Planning, writing and managing an API documentation project

We’ve started work on a new training course about planning, writing and managing an API documentation project. Primarily aimed at REST APIs, this will help you to organise, plan, author and control your API documentation. This course is aimed mostly at people who are not developers, and no programming experience will be required.

The exercises are based around an imaginary API for hospital management system, as most people are familiar with what a hospital is, and what happens inside.

We have have completed the presentation, bar a few teaks, and we are now developing the course exercises and answers. The slide deck currently runs to 256 slides, which means this will almost certainly be a two day course.

We think this course is probably best suited to being delivered in a classroom. We may also offer it as a live, web-delivered course using webinar software for teams based outside of the UK. We might develop a recorded e-learning course at some point in the future, but it’s not something you’re likely to see for a while.

For more details, see Documentating APIs – training course.