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:
Fabricator (http://t.co/XWkOvgmom5) looks like a great tool for component-driven development and documented code (i.e. style guides).
— Paul Lloyd (@paulrobertlloyd) April 17, 2015
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:
- Someone looking to use your components
- Someone looking to contribute to your components
Or, put differently:
- Usage instructions
- Design & development instructions
Perhaps even:
- Someone working on a new or existing product using these components
- 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?
Developer
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.