Documenting your Component Library: Who's it for?

I was made aware of the impressive looking Fabricator from Paul Lloyd earlier today, but it reminded me of a thought process we went through with Dough. Here's Paul's tweet:

After looking through the tool (which is excellent), it brought up a small but maybe significant point, in that the Javascript documentation lives separately. We initially did the same with Dough, but I think it's worth exploring some of the thinking:

Who and what are you documenting for?

This could fall into a couple of categories:

  1. Someone looking to use your components
  2. Someone looking to contribute to your components

Or, put differently:

  1. Usage instructions
  2. Design & development instructions

Perhaps even:

  1. Someone working on a new or existing product using these components
  2. Someone improving or creating a new component, which will then be used on a product

With Dough, and pretty much any other component library like this, we obviously want both usage and contribution.

Browsing a well kept component library gives a clear picture of what's available to use, and also highlights areas that are missing or need improving. But we need to remember that our target audience isn't just designers & developers. To get real benefit from the library, the rest of the company should know about it too. It helps people visualise how tools and products are put together, and make better decisions.

For bringing new hires up to speed, encouraging contribution (inside and outside the organisation), consistency, prototyping, it's clear this stuff works.

Some scenarios

Product designer

I want to see what components are available. I probably don't want to see components filtered by implementation (JS/non-JS). I'm interested in a list and to see how they work on mobile, what they look like, etc. Granted, I might not actually click on the Javascript section, but if that's there, am I even in the right place?


I'll want to browse the library to see what's available. I'm probably already in Github looking through the code. I'll be investigating exactly how these things have been made at a lower level than this set of documentation. I'll eventually want to know how to exactly how to write the code for a new one of these things.

Why would you separate Javascript docs?

As an example, Dough, with a tweak or two, follows Airbnb's Javascript Styleguide which goes into far more depth than I believe a component library needs.

I'm not sure tacking the above on the end of the component library seems right. How far do you go? It also use helpers written in Ruby on Rails, do these belong here? How about the more general Ruby styleguide?

The documentation could quickly become a behemoth and too general to be useful to everyone who could influence product design.

I'm hoping by this point that you can see how the answer isn't immediately obvious.

Of course, there is no right way

Every case will be different, and the scenarios above describe some of the situations in the organisations I've worked in.

To get everyone in the organisation living and breathing your component library, it needs to be useful to everyone. With better awareness, the organisation knows what the library has at its disposal, and can ultimately get more and/or better (choose your metric!) products out there, sooner.

The risks of not getting this stuff right are bigger than they may seem – you can craft the best component library & workflow out there, but if your design and product teams aren't fully in the loop, you'll end up with more inconsistency than you had before.

I think my conclusion to this post is that I prefer to separate implementation documentation from usage documentation. If you've read this far though, you probably already guessed that.

Making with Dough

Over the last year, the Money Advice Service has been putting together a reusable component library for use on our site. It’s called Dough and it’s now powering nearly all of the common UI elements across a suite of around twenty five tools, calculators and websites. It’s completely open source and available for you to use too.

Dough is a collection of server side helpers that generate markup. Simple yet powerful – there is a single copy of the HTML for documentation, tests and live implementation. Change once, change everywhere.


These bits of markup are then styled, initially by Dough’s base CSS, and then by a ‘theme’ layer. We chose themes for a couple of reasons;

  1. We’re open source, and themes make Dough easily fit any design style
  2. We have a couple of visual styles at the Money Advice Service – the main site, and the blog and so each have their own ‘theme’ for Dough


We’re a public organisation and reaching the widest number of users is a major priority. Our components are fully tested in house and with our partner agency, Digital Accessibility Centre.

We believe this makes our component library pretty unique and goes the extra mile in making our tools as wide reaching as possible.


Where necessary, these components are then enhanced with unobtrusive JavaScript. There’s no special treatment for this – each bit of component markup is simply stamped with a data attribute that our JavaScript will then target. For example:

<p class="component" data-dough-component="Tooltip">
  <p>Tooltip text goes in here</p>

All pages include the small ComponentLoader.js file which will scan the DOM for all Dough components. It’ll then go and fetch the relevant JavaScript (with requireJS) for those components that need it, and boot them all up with a promise (polyfilled by RSVP.js) that components can resolve or reject. We do this to ensure that the state of the components is centralised.

There’s also a common interface from which all components inherit to ensure consistency in code and behaviour.


All components have JavaScript tests written in Mocha and Chai, run in PhantomJS by Karma (our preferred test runner.) There’s a few other plugins in there which you can see in the package.json, but that’s all there is to it.

For the Rails-based helpers there is a solid RSpec suite of tests to ensure the inner workings of Dough are behaving as they should.

Alongside automated testing, knowing that we’re working with the same markup everywhere gives us assurance that things are going to be consistent. Confidence also brings flexibility – everything running from the same markup means we can iterate quickly and see the affects reach across the entire suite of tools.

In the real world

We’ve just launched our Retirement Adviser Directory which makes heavy use of Dough (mostly it’s form helpers.) These will generate our preferred markup for form elements, and handle our style of validation.

Aside from working out what to ask the user, using Dough meant we no longer needed to spend time thinking about how much space should be between fields, how wide they should be, what the focus state should look like, how validation should work, etc.

What’s next

Dough targets Ruby on Rails as that’s what our tools are built in, but we’re interested in making this more agnostic.

Obviously this isn’t a golden hammer. It’s not going to make our projects so trivial that we barely need designers and developers. It allows us to focus on the bigger problems we’re trying to solve. We believe that time is better spent working on how we can provide value to the users we’re aiming for, rather than designing a submit button every time a new project starts. With Dough, you can prototype with production code, which means we get ideas out to users sooner and iterate faster.

We’re working on a front-end for Dough – “Made with Dough” – which we hope will be a resource for how to get started, how to contribute and all other things Dough.

[This was written for the Making Money Advice Service blog, and has been cross posted here.]

Working in the open

Over the past couple of months, the Money Advice Service has taken the approach of coding in the open, by using public github repositories. As a reasonably large organisation using open source software, I think opening up the code has big benefits. People get to poke around under the hood, and might even be able to get something from it. All the projects are licensed under MIT, so are free for everyone to use & abuse. They may even get some pull requests from anyone feeling particularly generous. Who knows.

It's particularly pleasing to see this attitude coming from another government organisation, and well worth a look.

Saying “the geek stuff is your job” is no way to launch a startup

As developers in a time where everyone wants their own side project/startup/the next <insert latest cool company here>, this is surely our time to shine. It’s hard not to notice that developers, designers and general ‘web experts’ are becoming increasingly in demand for these sort of things.

So this is a good thing?!

As a web developer in London, frequently I will meet someone who wants their own NextBigThing startup, and a healthy chunk of geek time along with it.

As people who provide a service (make once, sell once) rather than a product (make once, sell many), the only asset we really have is our time. How we use it, charge for it, or give it away pro-bono is up to us.

This is the way of things, and I guess how things will stay. My issue though, especially after reading this ‘using words like blogsite is unacceptable journalism’ rant, is this scenario:

In a pub:

Them: Hey, so I’ve got this great idea for a music startup. Me: Cool, I love music. Tell me about it. Them: Ok so it’s a bit like Spotify, but does x, y and z differently. I also have these great contacts that will help it get ‘out there.’ Me: Sounds cool, let’s chat about it.

At the first meeting (…probably in a pub):

Them: So yeah, the reason I asked you is because I only want to do this with someone who’s really into music. Me: Definitely. Any thoughts on how we should put this thing together? Them: Ha! No idea, that’s your job. I know nothing about this sort of stuff.


Firstly, the hypocrisy of this whole scenario is a little frustrating. Mandating that you’ll only work with someone who’s into your stuff, when you’re not interested in even dipping a toe into how your potential business partner might work is… suboptimal.

Ambition, aspiration and hard work are (so I’m told) essential when it comes to building a company, but shoulder-shrugging about the very platform you’re building it on seems naive. I understand that most partnerships have complementary skillsets, but surely some overlap is important.

If you genuinely want to launch a startup that is predominantly on-the-web, then wouldn’t it be wise to know a little bit about it?

[This was cross-posted on Medium]

Animate on Arrival

A week or so ago I tweeted about a trend I've been referring to as 'animate on arrival.' Since then I've been seeing more and more of them, and a) wanted to write about it because I haven't written in a while, and b) compile a list of them. The reason it caught my attention is that without realising, it really made me focus on the content and actually read the thing. To demonstrate, I've listed a few decent examples below and I'm also keeping the others I find tagged on Delicious.

Apart from all being beautifully designed ― the top 3 particularly ― they were all launched within a few weeks of each other, got quite a bit of attention and of course all featured this technique.

Anyway, I really like it, and if you're using jQuery just drop in jQuery Waypoint, add a class to trigger your CSS animations, SVG fills or whatever and everyone's laughing.

And that's that.

Taking the scenic route

When I was 12, I took up the drums. Like any instrument, or indeed any new skill, there's an endless amount of seemingly boring stuff to muddle through after the initial excitement has waned. I'm talking about the vocab of learning a language, the admin of starting a business, the theory of a driving test. In the case of the drums, amongst them were the rudiments. "You've got to learn your diddles, paradiddles, drags and flams to be a good drummer," I'm told. Apart from being fun to say, these are repetitive exercises designed to improve technique. Perhaps typically of my often short-sighted ways, I saw no immediate benefit to learning them... "yeah right, as if the Metallica drummer does this rubbish."

I took this attitude, put the headphones on and just played along to the music I wanted... the fun stuff. That's why I took up drums in the first place. This was an ongoing theme until I discovered that the more experience I had, the more I could appreciate what other drummers were doing. I remember vividly how blown away I was by the speed and fluidity of these guys, something I hadn't really noticed or respected before, and wanted to spend every shred of time I had learning to imitate. A few awe-inspired discussions after an impressive gig revealed their secret.

Taking a slightly more indirect route to my original goal, 'just playing along to music,' made it all the more achievable. Pushing myself to learn these unnecessary things only made the necessary things easier, smoother and more natural. It became addictive; the more I did the boring stuff, the more liberated playing for fun became. The flipside is that the more I understood, the more crushing revelations of how much more there was to learn showed their ugly heads. All the more to get going with, then.

Of course, hindsight makes all this seem hideously obvious now.

Back to today, in the world of the web and this experience is more relevant than ever. I write this now because Twitter's recent changes to their API policy has resulted in three months of evening side project work being flushed down the toilet. As frustrating as this was, I tried a new approach to the way I tackled this project and just like it was with the drums, learning these new techniques only deepened my understanding of the ones I already knew. I'll call that progress, and I'll take it.

(Thank you, Twitter.)

Cf: paradiddles are important.