Tech Talk: Creating API Tutorials with Slate

In a recent blog article we explained, how we use Swagger to document our Platform API methods at Documill. We have found Slate a useful companion utility for Swagger in writing the API tutorials to show, how our services can be used.

In a nutshell, Slate provides

• easy document creation using any text editor
• versatile publishing options
• nice layout and responsiveness
• freedom from technical hurdles (once set up)

Easy document production, versatile publishing options

Slate generates a single stand-alone documentation web page with all the required resources, such as style sheets. These can be served as a static website or packaged as part of a dynamic web service, or even automatically published to a Github project. The generated web page is responsive and works well on both desktop and mobile browsers.

The tutorial documentation is written using the simple Markdown syntax, a standard lightweight markup language used in various services such as GitHub. This allows easy editing in any text editor.

The following is the source code of a section of an API Tutorial of ours:

Here is a screen shot of the final tutorial:

Setting up Slate: some patience required

The Slate system is very easy to use once it has been set up. However, setting it up initially can be a somewhat difficult task if you have no prior experience with the Ruby platform it is based on. Fortunately, Slate authors provide a Dockerfile that outlines the steps on how to set up the build environment. The steps need to be adapted to your own operating system, which can take some effort.

Once the Slate’s build system is set up, creating the tutorial involves simply writing it and running a few build commands each time you want to generate the documentation web page. To make the whole process even simpler, we have written the steps into a Maven build script that builds the web page and packages it into a web application that can be deployed into a server.

Write, not fight!

Overall, we have found that Slate works well after the initial hurdle of setting it up. It meets the requirement of providing our users with clear and usable documentation. And it allows us to concentrate on the actual writing instead of fighting with the syntax or build system.