Documenting Patterns is a Designer’s Job
Original Article from my blog →
https://francescoimprota.com/2022/02/01/documenting-patterns/
“Writing documentation is a boring job. In addition, it’s upon the dev team because of coding. “
This reasonable statement is the classic designer’s parachute.
Above all because of the code.
I think it comes from a legacy of a past where software solely was designed, coded and documented by computer engineers.
Designers were late to the party.
So, we adapted to a pre-established system.
Today, however, we could lead the entire process, acting as a link between teams, departments and stakeholders — or rather must do
We are privileged. We just have to make good use of it.
For this reason, I believe that anyone who loves (and cares) designing software interfaces cannot refrain from the task of documenting the patterns library that he himself has designed or contributed to.
Dimensions, styles, variants, content. All these are design elements.
We shape them in out preferred design tool.
We makes choices, foresees scenarios.
So, we are the repository of meaningful information that must end up in the patterns library.
Our work never ends up with a mockup or a Design Kit.
But naming things is freaking hard
I read this sentence on a lot of websites, blogs, LinkedIn posts and more.
Well, it’s true. If we can’t describe what we create, we’ve have done half the work.
Patterns or Components?
A pattern library — which may also be referred to as a component library — is a central and digitalized collection of a brand’s reusable assets.
It’s totally different from a Design Kit.
It lives in the browser.
And you have to know little about code to work on it.
Today, the designer’s toolbox should include new things: Fractal, Style Dictionary, Storybook, PatternLab and more.
You simply can’t avoid to know and use them.
The Pattern Card
In my workshop on Design System there’s a moment of practical exercise in which I ask participants to try their hand at a pattern card.
It’s interesting — and fun — to see the people reaction (90% are designers) putted in front of this task: they’re quite confused and don’t know where to start or what kind of information they’ve to write, even though knowing those UI elements.
What Include
First of all, we should check what kind of info to put in it:
- Pattern Name — use a name you and your team can memorize and quickly refer to
- Description — succint description of the pattern focusing on what it allows to do, not what it is
- Usage — what do users need to know in order to properly implement this pattern? Discuss any UX, Visual, Frontend, Accessibility, Content, Backend, etc. Show do’s and dont’s. When should users consider an alternative pattern? Include links to internal and external resources.
- Variants — specifiy any pattern variations: size, spacing, colors, etc.
- Preview — live preview of the pattern
- Code — the pattern template (HTML or whatever) and related assets (CSS, Sass, Javascript)
- Meta Info — additional informations like pattern’s status (work in progress, draft or published), changelog, version number, dependencies or anything more that you need
Benefits
Getting your hands dirty with a Pattern Library will bring you
three key benefits as designer:
- Expand your product knowledge, following all steps of the project from rough sketches to final implementation
- Improve communication with developers, speaking the same language
- Be aware of technical constraints, making more aware design decisions
Exercise Yourself
Now, I’d like to do the same exercise with you. Think of a pattern/component you have been working on recently and describe it.
You can use the file I prepared for my workshop (it’s in Markdown, but choose the format you’re most comfortable with)
Dowload the pattern card template
When you are done, you could share your work with me if you want
(leave a comment or send me an email to me[at]francescoimprota.com)
I would love to discuss it together.
Have fun!
