This post will explain how our team was able to greatly reduce the friction in writing documentation guides by standardizing on a toolchain that other projects can use.

A Bit of History

Before there was ClojureWerkz, myself and Alex were fairly active in the open source community. I maintain several RabbitMQ clients and needed a new documentation site for one of them.

So I put together a doc site based on Jekyll and Alex helped me with styles. This toolchain has evolved a bit and when we were looking at writing documentation for Monger and Langohr in late 2011, we decided to just base them on what we already had and knew: that Jekyll site amqp gem was using.

ClojureWerkz grew and we kept reusing the same thing over and over again. By June 2013, ClojureWerkz has accumulated about a dozen of projects that have substantial documentation guides. Writing, editing and maintaining these docs took time and in the process, we’ve found ourselves repeating a lot of things between sites.

It’s easy to notice a lot of similarities between, say, Elastisch docs and Langohr docs. We also try to take good ideas from doc sites developed later and feed them back into older sites.

So we needed a standard toolchain that all these documentation projects could use. In particular, we wanted it to give us a very fast way of writing the first couple of guides before we would worry about finer details and editing.

Enter ClojureWerkz Docslate

Docslate is a relatively unknown project. We don’t write about it on this blog. It does not get updates very often. It does, however, play a major role in ClojureWerkz: powering our documentation guides and making writing them a more pleasant and straightforward process.

What Is Docslate

Docslate is a Jekyll site with predefined structure and integrated Twitter Bootstrap. Once you have it going, with just a few edits you are ready for the work that really matters: writing helpful documentation guides.

Why You Should Adopt Docslate For Your Project

Docslate lets you get to writing quickly without spending too much time on issues such as

• Should I use Jekyll, Awestruct, hack my own thing with Pandoc or use a wiki?
• What library should I use for code highlighting?
• How do I make the docs look decent?
• What licenses should I use for the site and content?

and so on.

It’s dead easy to put together a pretty good documentation site with Docslate and then work on copy and styling once your first version is ready to go live.

How To Get Started With Docslate

Since Docslate uses Jekyll, you’ll need Ruby (any version, although we typically use 2.0 or 1.9.3 these days) and RubyGems installed.

Then install Bundler with

gem install bundler

Clone Doclsate Git repository with

git clone git://github.com/clojurewerkz/docslate.git my-project-guides

Change to your local clone, remove .git directory and re-init the repo (Docslate is simply a starting point, your doc site should really be in a new repo):

cd my-project-guides
rm -rf ./.git
git init
git add .
git commit -m "Initial commit: Docslate"

Then install dependencies with Bundler:

bundle install --binstubs

and you are ready to run a development server with

./bin/jekyll serve --watch

then navigate to localhost:4000.

The site you’ll see is very similar in structure and styles to Elastisch docs, Monger docs, and so on.

How To Add Content

Docslate assumes your documentation guides have an index page, a ToC page and one or more guides. The index page is in HTML and can be found in index.html in the repository root.

The ToC page is in Markdown and can be found with individual guides under articles.

Docslate contains 3 pages for you to start with:

  guides.md
  getting_started.md
  community.md

guides.md is the ToC page. getting_started.md contains the Getting Started guide. Finally, community.md gives you a page to list information about the project, its mailing list, IRC channel, Twitter account, and other things you need to make your open source project really awesome.

Adding new guides is as straightforward as adding a Markdown file to the articles directory with the header (title, etc) Jekyll expects and linking to it from the ToC page.

For example, to add a guide on extending your library, create a new file at articles/extensions.md, add Jekyll header to it, make sure development server is started and navigate to localhost:4000/articles/extensions.html.

How To Customize Layout

Layout files can be found under _layouts. There are two layouts available:

• Default layout
• Article layout

Article layout is used to display individual articles (guides), default layout is used for everything else.

How To Customize Styles and Assets

Styleshsets and JavaScript files can be found under assets/stylesheets and assets/javascripts, respectively.

How To Generate The Site

Use

./bin/jekyll build

to generate the site for deployment. Site root then will be under _site. This directory is what you will deploy. It only contains static assets so deployment usually is as straightforward as rsync-ing files to your server and serving them with Nginx, Apache or any other Web server of your choice.

Where To Go From Here

Docslate is a starting point. It is meant to be customized for your project’s needs, styling and so on. Feel free to do it, add JavaScript libraries you need, upgrade and customize Twitter Bootstrap, and so on.

Wrapping Up

Docslate was born out of a dozen documentation sites we have for ClojureWerkz projects. It’s a battle tested, easy to use toolchain that provides you a good starting point and is completely open sourced under a reasonable license.

Now you don’t have an excuse to not document your open source project well!

Michael on behalf of the ClojureWerkz Team.