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
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.
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
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.
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
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.
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
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
add Jekyll header to it, make sure development server is started and navigate to
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
How To Generate The Site
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 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!