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
- 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
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.
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.
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.