How to build an API docs site using Slate

If you want to build a simple but attractive looking API documentation site, you can’t really go wrong with an open-source tool like Slate. Despite being created by a teenager developer during a summer internship, it has become an incredibly popular tool with the project being forked more than 15,000 times and with well-known organisations including NASABest Buy, Monzo and Skyscanner all using it.

🎬 So what is Slate?

Slate is a Ruby-based tool that generates a great-looking, three-panelled API documentation static site from a set of markdown files. It was built by developer Robert Lord in 2013 when he was an 18-year-old intern at at travel software company Tripit. He convinced his boss at the time to let him open-source the project and the rest is history.

He told me found it pretty surreal that so many people were now using and maintaining his “buggy project” nearly six years later. However, the results speak for themselves — you can see some examples in the Slate in the Wild repository.

🛠️ Before you Begin

So before you begin, make sure you have met the following requirements:

  • You have an Open API/ Swagger file in .yaml or .json format.
  • You have installed Node.js. This includes npm (Node Package Manager).
  • You have installed swagger-to-slate or widdershins (or similar) to convert your file into Markdown. I used the former in this example.
  • You have installed Vagrant and VirtualBox.

In this example, I’m going to use the generic Swagger Petstore example which I have saved to my Desktop and called petstore.yaml. To convert this to Markdown using swagger-to-slate, open a terminal and run:

swagger-to-slate -i ~/Desktop/petstore.yaml

This saves a file called petstore.md in the same location as the .yaml file. Once you have this, you can get started with Slate.

🔨 Build your site using Vagrant

To build your API documentation site using Vagrant, follow these steps:

  1. Go to the Slate repository on Github.
  2. Click Fork to create your own fork of the main repository.
  3. Clone the fork to your local machine using git clone. For example:git clone https://github.com/<your_github_username>/slate.git
  4. Go to ~/slate/source and remove the index.html.md file.
  5. Rename the Markdown file you created earlier as index.html.md and copy it into the source folder, changing the file locations as required:
    cp ~/<local_path>/index.html.md ~/<local_path>/slate/source/
  6. To build your site using Vagrant, run: vagrant up
  7. Go to http://localhost:4567 to see your site. It may take several minutes to build.

🐳 Build your site using Docker

You can also use Docker to create your site but you must edit some additional files. Although this method is not officially supported, I had no issues when I tried using it.

If you are using Ruby version 2.5.1 or newer, you will need to create three files:

  • .dockerignore :
    .git 
    source
  • Dockerfile :
    FROM ruby:2.5.1
    MAINTAINER Adrian Perez <adrian@adrianperez.org>
    VOLUME /usr/src/app/source
    EXPOSE 4567
    
    RUN apt-get update && apt-get install -y nodejs \
    && apt-get clean && rm -rf /var/lib/apt/lists/*
    
    CMD ["bundle", "exec", "middleman", "server", "--watcher-force-polling"]
  • docker-compose.yml :
    app:
      build: .
      ports:
        - 4567:4567
      volumes:
        - ./source:/usr/src/app/source

After you create these files, follow these steps:

  1. Add the Docker files to your local Slate directory.
  2. To build your Docker site run: docker-compose up
  3. Go to http://localhost:4567 to view your site.

For alternative Docker methods refer to this documentation.

💎 Build your site using Bundler

Alternatively, if you want to run your Slate site locally, you can also use Bundler. To use this method you must install Ruby version 2.3.1 or newer. To check which version you have installed run: ruby -v

If you need to install Ruby, see the installation documentation for the different methods available.

Once installed Ruby, you can install Bundler: gem install bundler

To build your API docs site using builder:

  1. Navigate to your Slate directory: cd slate
  2. Install the dependencies such as Middleman specified in the Slate Gemfile: bundle install
  3. Launch the Middleman static site generator: bundle exec middleman server
  4. Go to http://localhost:4567 to see your site.

That’s pretty much it! Good luck.

Advertisements

The Story behind Slate: An Interview with Robert Lord

Back in 2013, developer Robert Lord, then an 18-year-old intern at Tripit travel software company, was challenged to create an API documentation tool by his boss. It took him several weeks but the result was a beautiful, responsive API documentation generator called Slate. Five years later, it has grown into a popular open-source tool that is used by a number of global organisations and companies including NASA, IBM and Coinbase.

cover-image-for-above-the-entire-post
Robert Lord created Slate while interning at Tripit. Copyright© Concur Technologies,

Lord said the Slate project grew out of a set of requirements the Tripit engineering team had at the time. He said: “I was interning at TripIt and my boss pointed me towards some two-column documentation pages and said ‘We’d like a page like this for our new API.’ They also had the requirement that their technical writer could make changes, and I think they didn’t want to write raw HTML. I made a generator that ended up being pretty generic to any documentation, and convinced them to let me open source it.”

How to Use Slate

Slate is simple to use, you fork the Slate Github repository and create a clone. Next you customise the code to meet your requirements; adding a custom logo, fonts and any additional CSS styling in the source folders, before adding your API endpoints and their descriptions in Markdown.

screenshot-slate
Slate helps users to create beautiful, intelligent and responsive API documentation.

When you’re done, you start Slate and launch your API documentation site using Vagrant or create an image using Docker. The result is an attractive, responsive three-panelled API documentation site with code samples in multiple languages down one side and a smooth scrolling table of contents down the other. For more information on how to use Slate, follow the instructions in the Slate README.

Slate in the Wild

Today more than 90 people have contributed to Slate on Github, it has been forked more than 13,000 times and has been given more than 23,000 stars. Some of the organisations and companies listed as users include NASA, IBM, Sony, Monzo, Skyscanner and Coinbase. There is a list of more than 90 companies that have used it on the Slate in the Wild sub-page of the repository.

This slideshow requires JavaScript.

Lord admits he still finds it “pretty surreal” that such large companies have adopted what he labels the “buggy project” he created as a teenager. “I really did not expect anybody else to see it or care about it,” he said. “Slate never really had a big rush of new users all at once, the growth in stars has been more or less linear over the years. No hockey sticks here. So there was never a single moment where suddenly a bunch of people were using it, it was a very slow process of discovering one company at a time.”

Life after Slate

Interestingly, a year after working at Tripit, Lord interned at Stripe, one of the leading API-first companies whose own API documentation inspired him when creating Slate. Stripe realised the value of their product hinged on people being able to read and digest their APIs. They invested a lot of time and effort in developing their own in-house API documentation tool and set the bar for the rest of the industry with the two-panelled design that has inspired so many other API tools.

Lord had plans to develop further API tools but decided to focus on other things. “Initially had some plans for similar tools,” he said. “But I think I realized I’m still early in my career, and would rather branch out and work on a variety of projects instead of focusing in on just one area.” Despite moving onto other projects and being fairly modest about the success of Slate, it’s an impressive piece of work for the young developer to put on his resumé. Indeed, one of the main reasons he asked Tripit to allow him to open source the project was so he could show future employers his work. “I mostly convinced them to open source it just so I could point future employers to this chunk of code I wrote,” he said. One company clearly took notice, Lord starts work on Fuschia at Google in a few of weeks time.

Five Reasons I’m Falling Out with Confluence 

After a tumultuous and slightly short-lived affair with Sharepoint, I was introduced to Confluence and I was quickly won over by its simplistic UI and text editor. However, three years later I’m starting to feel disillusioned and frustrated with it. Here are some of the reasons why:

1. Bloat

Confluence has become bloated. I’m not sure if it’s a result of popularity or customers’ demands for new features but the feature set has been bloated while the basic functionality is neglected. It’s like a pet dog that has become fat and lazy from too many treats.

160402182953-tease-overweight-dog-update-irpt-full-169
Confluence now and Confluence before …

2. Bugs

Any frequent user of Confluence will be aware of the numerous bugs that seem to go unfixed for long periods of time. We encountered  a bug last week where images were breaking when copying a page (we later discovered this was caused by the image name having a colon).

Another common bug, which has caused me grief in the past, relates to being unable to export pages as PDFs for various reasons. This case, first reported in 2014, is still affecting customers two years later: https://jira.atlassian.com/browse/CONF-34275

2017-03-19 12_43_51-Clipboard
An example of customer frustration…

3. Plugins

To do anything useful or practical with the vanilla version of Confluence you need to install expensive plugins. Want to use versioning? You need buy a plugin. Want to translate your content? You need to buy a plugin.

2017-03-19 12_59_12-Films & TV
Even “Atlassian Verified” plugins don’t seem very reliable and are often costly.

Apart from the additional costs, my main issue with this is only a handful of plugins are built and maintained by Atlassian so you either have to take the risk of using a free plugin that will break in the future or you have rely on a third party developer to continue supporting it to ensure it works with newer versions of Confluence.

4. Basic Missing Features

The basic text editor in Confluence, the thing at the heart of the software, is still pretty poor and even things like basic formatting are a chore unless you manipulate the CSS.

2017-03-19 13_20_33
It amazes me Confluence still doesn’t offer other fonts or the option to change the font size.

Off the top of my head, the things that annoy me include: you can’t insert certain macros directly after another macro or a table because they will break or it will mess up your formatting, you can’t create a table without borders (unless you have Source Editor), you can’t choose different fonts or font sizes (unless you import them in the CSS), you can’t change the background colour, you can’t justify your text and you can’t remove historical attachments that have been uploaded to a page in the past. These are all things I’ve just accepted as Confluence-isms, things you just have to accept that Atlassian aren’t going to fix any time soon.

5. Cost

Despite all these things, Confluence is not cheap. If you’re a company with 100 or more employees, the Cloud version will set you back 3,000 dollars (£2,419) each year:

2017-03-19 13_24_50-New notification
Ouch: Confluence is not cheap!

On reflection, it’s pretty scandalous how much they are charging when so many bugs still exist, basic text editing functions are missing and most companies will need to install and pay for further plugins to get it to meet their requirements. Unfortunately, until someone comes up with a decent alternative I don’t see things changing.

Have you found a decent alternative that can be used for wiki content or software documentation/online help? If so, please let me know!

How to become a Technical Writer

If you’re an analytical journalist who is looking for a change, a budding writer with an interest in technology or an experienced programmer who is secretly an aspiring wordsmith, then technical writing might just be the answer for you.

What is a Technical Writer?

Technical writers or authors help to communicate technical information and instructions for products, such as software and hardware, in a way that is easy to understand. This can include writing user manuals, online help, release notes, integration guides, fact-sheets, wikis and APIs among others. Other methods of communicating information include producing video tutorials, graphics and illustrations. If you’ve ever read the mini instruction manual that came with your smartphone or clicked the ‘?’ icon or ‘Help’ button while using a piece of software then the content was probably written by a technical writer.

The role is sometimes given other names such as technical communicator, documenter, information designer and content strategist. Occasionally the content is written by developers or business analysts.

Moving from Journalism into Technical Writing

After nearly six years of writing for local newspapers and witnessing more and more job cuts as readership declined, I decided to jump ship and try something new.

Side profile of a journalist typing on a typewriter

My lifesaver came in the form of technical writing, and while it might not be for everybody, I knew straight away that it was the right move for me. Skills I had used for years such as interviewing, writing shorthand and producing accurate copy quickly proved to be very much transferable but instead of interviewing local politicians and press officers to write news stories, I was speaking with developers and testers to produce release notes and user instructions. Similarly, my multimedia skills and experience with Photoshop and video editing came in handy for creating graphics and video tutorials. It certainly helped that I’d always been interested in computers and had worked on blogs (so had some basic knowledge of HTML etc) but I found most aspects of the job just suited my existing skill set.

What Background should a Technical Writer have?

While I have encountered that some companies who would rather hire technical writers with a coding or technical background, I don’t think that should be a stumbling block if you’re interested in pursuing a career in technical writing. I have met technical writers who have previously worked in customer support, higher education and even photography. Although I have personally found my journalistic skills incredibly useful, I think as long as you are a good writer, are able to think analytically and are happy to constantly learn new things then a career in technical writing could be for you.

The sections below will provide tips and advice that will help you if you are considering pursuing a career in technical writing:

1. Qualifications

Some employers will look for a degree in computer science or similar but requirements can depend on the subject matter of what is being documented. Degrees in science, engineering and English are all suitable.

While there aren’t actually too many universities which offer accredited technical writing courses, it certainly wouldn’t hurt your CV to have some kind of formal training in technical communication. The University of Limerick offers a graduate certificate in technical communication (distance learning), while  other universities such Imperial College and Norwich offer more specific or specialists courses such as science communication and communication design.

Introductory and more advanced courses with accreditation by the Institute of Scientific and Technical Communicators (ISTC) are offered by Cherryleaf, Armada and ESTON.

2. Commonly Used Tools

Another key thing that most employers look for is experience with the required publishing tools that their documentation team use or have used. The table below lists many of the products and tools that are commonly used by technical writers, although there are many others:

word_2013  Microsoft Word  Word processing tool.
sharepoint2013  Microsoft SharePoint  Documentation management tool.
default-space-logo-256  Atlassian Confluence  Documentation management/ team collaboration.
icon-flareLargeBgColor  Madcap Flare Help authoring tool.
FM-icon  Adobe FrameMaker  Document processing tool.
2016-05-18 12_27_22-Films & TV  Adobe RoboHelp  Help authoring tool.
Adobe_Acrobat_DC_Icon  Adobe Acrobat  PDF reading and editing tool.
Notepad  Windows Notepad  Plain text editing tool.
notepadplusplus.6.9.1  Notepad + +  Text and source code editor for Windows.
Adobe_Photoshop_CS6_icon.svg  Adobe Photoshop  Image and photo editing software
Visio-icon  Microsoft Visio  Diagram and flow chart creation tool.
visual_studio_2012___windows_startscreen_icon_by_revisionzero-d5qnp17  Microsoft Visual Studio  Integrated development environment.
greenshot_0a  Greenshot  Screenshot capture and editing tool.
img_snagit-icon  Snagit (TechSmith)  Screenshot capture and editing tool.
icon128-2x  Camtasia (TechSmith)  Screen recording and video editing tool.
Adobe_Illustrator_Icon_CS6  Adobe Illustrator  Vector graphics creation tool.

If you haven’t used any of the software listed above, it is possible to download 30-day trials of some of these (Adobe Software especially) and either play around with them or watch some tutorial videos online and read online help to learn how they work. Many open source tools such as Greenshot and ScreenToGif, which can be used to create .gif files from screen recordings, are completely free to download and use.

Another useful tool to use when starting out as a technical writer is to buy a copy of the Microsoft Manual of Style. This is a great everyday generic style guide that can be used as a guideline for your own technical writing or as a template when creating a style guide for an employer.

3. Coding Skills

While it is not essential, as I said before, having some basic coding knowledge would be extremely beneficial if you are serious about becoming a technical writer. Some people recommend learning the basics of HTML, CSS and some XML at the very least.

coding-future

There are some excellent online resources where you can learn different coding languages. These include:

Codecademyhttps://www.codecademy.com/

Khan Academy – https://www.khanacademy.org/computing/computer-programming

Code School – https://www.codeschool.com/

W3Schools – http://www.w3schools.com/

There are more out there and there are also plenty of forums and tutorial videos available which should give you the basics. Starting a blog or creating a website online is also another great way to learn and develop your HTML skills at the very least.

4. Build a Portfolio

It’s difficult to build a portfolio when you are just starting out and do not have work experience but one option is to go to freelancing websites and find some documentation jobs, write submissions and use them for your portfolio, whether they get accepted or not. Another option is to find an open-source collaborative project such as Mozilla Firefox (and Thunderbird) where the documentation is written by volunteers. Click here for more information.

If all else fails then simply produce dummy documentation samples such as user guides or fact-sheets for existing products. It would be good to have half a dozen or so of different document types, preferably both user-facing and back-end, to really showcase your work.

5. Networking

Once you have the qualifications, knowledge of the tools and a small portfolio, it is important to network and develop contacts in the industry. It is a good idea to look up and contact firms which have existing documentation teams who might need a junior technical writer in the future.

networking

Alternatively, write a list of companies you’d like to work for and either check their career sections or email them speculatively offering your services. Other ways to build your reputation and network is to send your CV out to recruitment agencies who specialise in tech jobs, add contacts on Linkedin and attend technology job fairs in your local area to get your name out there.

Finally, good luck with your search!

Was this post helpful? Let me know if the comment section below.