Writing up my thoughts on Justin’s talk made me think about what I’ve been doing with style guides on client projects. Here’s a quick run-down.
I’ve used Jekyll to build a style guide before, and was quite happy with it. I did have a lot of tiny files by the end, though, and it did become a bit slow and frustrating. It was also a bit fiddly getting it to play nice with Grunt and a live reload tool.
Hologram
Most recently, I’ve used Hologram, and am pretty happy with it. It’s a Ruby gem that parses comments in your CSS and generates a Style Guide based on a template that you set up. I struggled a little with the set up, but once it’s going it’s a pleasure to use. Having the documentation and code samples right next to the relevant styles is very handy.
I find that it’s very well suited to small snippets (atoms and molecules kind of sizes, to use Brad Frost’s terminology), but it's not so great with larger snippets of HTML.
One worry is that it can make your stylesheets noisy. The comments are removed when compiling and minifying the SASS or Less files into regular CSS, so there’s no worries about extra size for production CSS. The development stylesheets become much larger and can become more difficult to read, though, due to the large comment blocks.
A living style guide
Lonely Planet’s Rizzo is the best example of a style guide that I’ve seen, and I want to aim for something like that for the next style guide I make. It’s the only truly living style guide I’ve seen: it uses the Views (templates) directly from the application rather than separate, manual, snippets of HTML.
One of the problems of working in an agency environment is that I don’t, or can’t, always get direct access to the application code: my work runs in parallel to the main application, but doesn’t touch it directly. This mean that something like Rizzo can’t be done anyway, so a separate Front-end style guide using Jekyll or Hologram is he way to go.