When I was releasing Intemporel, one question that I had to think hard was creating a documentation. It was the first time I had to write documentation for a project. I also thought that Intemporel is just a WordPress theme and I don’t have much to post on the documentation currently.
Identifying the Problem
So what exactly was the problem? While I could’ve completely ignored the need of documentation, it is a bad practice. I really wanted to write a few pages describing the basic functionality of the theme and how-to guides.
However, what I didn’t want is installing a Wiki software to write documentation of a small theme or writing on another WordPress installation — the two highly popular methods. Why? Because that meant another database, script and server maintenance, updates, database security. I wanted my concentration on development process and not maintaining another website.
Looking for Solutions
I started looking for the solutions. However, I kept Wiki or WordPress as the fallback. I refined my need and decided what I really wanted —
- Documentation should be easy to navigate
- All the major links visible at the right spot
- Search is great, but if there are just a few pages like less than 10, I would avoid search
- Neat and minimal layout
- Least maintenance – for updates and security
- Many Wiki-based documentations have an ‘Edit’ feature. I didn’t want that.
I looked for alternatives and the one I liked is Sphinx. Sphinx is a documentation generator written in Python written by Georg Brandl and licensed under the BSD license. However, I had to drop the idea for two reasons – I don’t know Python yet and my server doesn’t support that either.
What do Bootstrap website, Foundation website and Brackets website have in common? Well, the answer may not be obvious. Actually, they’re all hosted on GitHub Pages! Viola!
No. I really liked the idea of hosting that small website on GitHub, the place every programmer adores, but it didn’t really solve the problem — until I started working on Jekyll.
What is Jekyll?
Jekyll is basically a ruby gem that processes your content in markdown, stitches the layout files and include files together (like in PHP) according to few settings in the configuration file and produces final out as HTML pages. And when I say it is a ruby gem, I do not mean you need to know ruby language to use Jekyll for your website.
Jekyll is created by good people at GitHub. The Jekyll website calls Jekyll a ‘blog-aware CMS’. Yes, you can actually create a blog in Jekyll. And that’s the concept I’ve moulded to create a beautiful documentation website.
I like working locally. So I installed Jekyll on my machine. Jekyll has an extensive documentation on how to install it. Jekyll is a ruby gem, so to use Jekyll you must have Ruby installed.
The website can be hosted for free on GitHub pages. It can also be hosted on any server with Ruby and Ruby DevKit available along with terminal access. Or you can also use free plans for cloud hosts like OpenShift.
Jekyll is simple and easy to use and learn. But very powerful. There’s very less to configure, no databases to care about and supports Markdown and Textile. Code Highlighting is also available.
It’s highly customizable yet stable. It’s great not only for portfolios and personal blogs, but also for documentations of comparatively smaller projects – usually maintained by single person – that doesn’t need much features on user side.
To implement Jekyll, at first I developed a simple website with some CSS. I browsed and observed a lot of documentation website and hence got an idea what to design.
Later I generalized the idea and it took a bigger form. That’s what I’m going to introduce today.
Algomash is a Jekyll boilerplate with necessary operations for creating Documentation website for small projects. Algomash uses Jekyll and can be freely hosted on GitHub Pages. Yes, you read it right. It’s a Jekyll boilerplate. It has a homepage, a documentation area and a default responsive design that will suit most of the projects.
The core Algomash uses Pure.css which is a set of small, responsive CSS modules. It’s only 18 KB. You can use your own CSS. Pure.css is very light-weight and easy to learn UI library. It’s created by Yahoo’s YUI team.
Easy to configure
Open a text editor, add your site URL and title. Start adding content. While I’ve put the barebones together and have presented it as for a single project, it can be extended just by adding more categories alias projects in our case.
You can customize the design and structure of Algomash in your project however you want. You can use any UI framework, Bootstrap or foundation.
Yes, free as in freedom. You can download or fork Algomash from GitHub and start getting the job done. I’ve provided a neat documentation and step by step tutorial on how to create a documentation website for free. Algomash is available under GNU General Public License v2.0.
The whole Algomash website is actually the repository you would like to Download from GitHub.
So what are you going to document using Algomash? Which design techniques are you going to use? Also, what features would you like to see in Algomash?