Find out how much you can financially gain with Documill Leap through reduced costs and boosted revenue.Read more
Tech Talk: Creating API Tutorials with Slate
Lari Sinisalo · January 18, 2016 · 2 mins
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 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.
Defining the contract negotiation process and decision makers beforehand can speed up things radically - using new technology.Read more