EightShapes
Published in

EightShapes

Authoring Component Documentation

Model the Content, People, and Steps Involved

#1. Establish a Clear Yet Flexible Content Model

What sections will it have: Use When, How to Install, Accessibility? What are they called: Use When or When to Use? What form will each take: paragraph, bullets, table? What columns per table? What props are shown for each prop?

#2. Offer an Easy-to-Migrate Template To “Fill in the Blanks”

As a content model stabilizes, ease an author’s burden with a pre-built template in your authoring tool of choice. Don’t over-engineer a template with lots of tiny, inflexible fields or overlay too many standards on how to write adjacent to what content they compose.

#3. Agree on Voice & Tone Through Iteration

I’m an advocate for imperative language: Avoid, Never, Always, the works. Yet, voice and tone isn’t uniform for component doc across all organizations.

#4. Expand a Visual Language for What Doc Needs

Usually, system doc communicates using the system’s own visual style. As with any adopting product, the system may not cover all the solution that your doc needs. It can feel like extra work to finalize robust long form text, (orange?) signals for new items, and how to use alert colors (green=Do, red=Don’t, and yellow=Caution). These aren’t always what “real” products need first for their experiences, but nevertheless are essential for how your system communicates.

#5. Name One (or Two, or a Few) “System Editor(s)”

Useful documentation can come from anyone. However, it requires one (or a few) talented writers to ensure doc is high quality and fits together. Steeped in conventions, rapid in feedback, and sensitive to the subtle nuance that distinguishes rules from guidance, these editors are essential.

#6. Designers & Engineers Review Each Others Work. Always. Period.

As a core ethic of design systems, designers and engineers must work together to improve the quality of their shared output. When creating doc, that means that a designer should review the technical doc of a component they designed. Similarly, an engineer should have a hand in validating design guidelines. Both should pair to create examples that suit the needs of designers and engineers alike. Therefore, I make the designer and engineer a required reviewer of the other’s work. Period.

#7. Integrate Reviews by Community Members

Quality documentation comes in part from the inclusive participation of the design and engineering communities beyond the system team. That isn’t easy. Asking for feedback via an open call can feel like casting a fishing line into a pond with no fish and waiting for nothing to happen.

#8. Publish Incrementally, Since It’s Never Complete.

A code library requires code samples illustrating core usage. Design guidelines are a staple of any self-respecting design toolkit. Yet, while a component explorer is nice at the top, it’s not required. Doc is never perfect, covering every case and illustration. As you ogle Google Material from afar, I’ll let you in on a little secret. Their doc is incomplete too.

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Nathan Curtis

Founded UX firm @eightshapes, contributing to the design systems field through consulting and workshops. VT & @uchicago grad.