My own experience with Style Guides

Naga IT Services
Filed under: Industry, Process

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.


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.

Building a front-end style guide with Jekyll

Naga IT Services
Filed under: Talk notes

A few weeks ago Justin Slack of New Media Labs gave a talk about Front-end Style Guides (FESGs) for the Cape Town Front-end developers meetup. Below are my notes from his talk.

Justin talked about how FESGs are good for modular development, testing code early, and how they set a good precedent. They use real code and run in the browser, making them unlike regular style guides: they’re a living document. The Lonely Planet style guide is particularly impressive because it’s truly living: it uses an API to call view partials.

The options

There are a lot of generation options across a variety of languages: Rails, Ruby, PHP, JavaScript. Jekyll, a static site generator, is one option. A Style Guide needs to start incorporating content, so the fact that Jekyll uses Markdown is great because many content people use it.

Justin gave a short demo of setting up Jekyll and an explanation of how it works. It was great to see it in action. He noted that the built-in syntax highlighting is another good reason to use Jekyll. And, since it generates static web pages, it also has a very small footprint.

The demo

My favourite bit of his presentation was the demonstration of a real world example. Justin talked us through the set up, the thinking behind it, and the continued work on it. It was also great to hear about the bad sides of using Jekyll. Nothing is without its problems, and it was good to hear an honest discussion of the ups and downs. Some of the problems include the fact that it can be slow to use once you have a lot of files.

The next meetup

If we managed to get our skates on, we should be having another meetup next week: keep an eye on the meetup group for details!

Rape Crisis CTFEDs Hackathon: the seconding

Naga IT Services
Filed under: Projects

A few weeks ago, the Cape Town Front-end Developer meetup group for our second Rape Crisis Cape Town Trust hackathon. Although it went better than the last one, there is still lots for us to learn about the shape and structure of hackathons, and about how we can best help organisations like RCCTT.

What went well

The Style Guide is progressing nicely. We’ve got a Grunt set up to generate the style guide and get things moving along quickly, and we’re making good progress with it. We’re sort of aiming for a bit of a Style Guide driven development approach.

Even though it was after the hackathon, we managed to squeeze in some time to update the mobile Theme for the site to add some basic colours and branding to make it look a little more like the desktop site. This is temporary (it will fall away once the new, shiny, responsive is ready), but we think it was a useful short term solution, and didn’t take too long to do.

Using GitHub issues is still sort of working. Having a To Do list that you can grab things from, or assign things to people on is very handy.

What didn’t go well

Set up. Again. Even though most of us had the bits and pieces we needed on our machines (MySQL, PHP, something to run a local web server), we hit a few speed bumps when trying to run the site locally. For next time we need to be more on the ball about being ready: we need to be clear that everyone must have a copy of the site up and running on their machine before arriving on the day. The flip side to that is that set up problems are often easier to fix with someone helping, so leaving it to the day is tempting if you get stuck during the process. The other part of this is that we left it to the last minute. We’re all busy at our day jobs, and Saturday was there before we knew it.

We also got sidetracked by another problem on the live site. This is usual developer behaviour, and rightly so: when something is wrong on production, anyone who can help drops what they’re doing and tries to help fix the problem. There was odd behaviour from a particular WordPress Plugin on the live site: the Page Peel Plugin. The version of WordPress on the live site was updated, and that caused the Plugin to throw an error, which in turn stopped the widgets from registering. The widgets are basically all the little blocks that aren’t main content. For this site, that meant the homepage looked really broken! It was not a happy hour or so.

What to do differently next time

I really like how Zurb run their Wired events (their yearly 24 hour hackathon-like thing to help non-profits). Their recent post about it, Mobilizing Nonprofits Through Design Thinking, is inspiring, and has helped solidify some of the things we were thinking about from our recent experience.

We think we’d like to have a dedicated Project Manager for the day. That might be one of us developers stepping away from the keyboard for the day, or we could rope in one of our PM or Scrum Master friends from work. Having someone to keep us going and steer a bit would be really helpful.

On a related point, we’d also like someone from RCCTT there for the day to help guide decisions. It might also be interesting for them to see how this works, and what the hackathon actually entails. We would also be able to sneak in some content work with them. Another thing that’s on the back burner is a Content Strategy exercise for the site: having a RCCTT staff member on the team would mean that we could look at doing little bursts of that on the day.

BED, FED, Design

Naga IT Services
Filed under: Industry

Today’s google doodle is for John Venn’s 180th birthday. I did maths at university, and a love of numbers and stats and things has stayed with me. Since I’m a fan of charts and graphs, and Venn diagrams in particular, I decided to make a little one today.

At first, I wanted to do more flag waving and shouting about responsive web design and the One Web, but when I started sketching things out, I realised that it’s actually kind of complicated, and has a number of criss-crossing dimensions. That means it doesn’t fit Venn Diagrams too well. Instead, I want to show where I think Front-end developers live in the world of the web, using a somewhat simplified picture.

A Venn diagram showing that Front-end developers are a bit of a mix of back-end developers and designers

Back-end developers (BED) do all the behind-the-scenes stuff that makes a web site run, like Databases and APIs and things.

Designers do all the to-the-human stuff that makes a web site work well, like visuals, user experience, and things.

Front-end developers (FED) sit somewhere between the two. They have some design and interaction skills, and they have some coding skills. More importantly, they provide a bridge between the very tech-y side and the very design-y. They can speak bits of both languages, so they’re able to translate between the two.

Mix it up

I’m a strong believer in cross-functional teams: having a mix of skills and levels of tech and design skills across a team makes everyone smarter, better at being part of the team, and better at their jobs. I think that working with back-end developers and designers gives front-end developers a wider context to what they’re doing, and it helps them skill up. I certainly find this to be true for me. It goes both ways, of course: learning a little about front-end development makes back-end developers better at their job and designers better at theirs.

I hope to expand on this in the talk I’m giving at the UX South Africa conference in a few weeks time. Eek!