Pitt IT Professionals provides now faster and smarter staffing
"We are now fully in the driver’s seat. With the same team, we have significantly increased our productivity and the level of quality we offer our customers."
Read moreLari 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
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:
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.
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.
Written by
"We are now fully in the driver’s seat. With the same team, we have significantly increased our productivity and the level of quality we offer our customers."
Read moreFind out the correct order of obtaining Salesforce certification for you to become an advanced Salesforce admin, a consultant, a developer, an architect, etc
Read moreDan Tam Nguyen joined Documill at the beginning of 2022 as a Dynamo Solution Support Trainee. Welcome!
Read more