Component usage vs component development/implementation - guidance & storage
Problem
From Slack thread in UX channel...
A lot of the content in the component pages seems extraneous. My hypothesis is that the content is currently trying to serve 2 JTBDs:
- Component usage guidance - When using components, I want to understand best practices and patterns, so that I know IF and HOW I should implement the component in my features.
- Component development guidance - When building components, I want to understand what patterns should be embedded into the component programmatically, so that the component works in the way it was designed.
Both are important but I think we can streamline a lot of our component pages by separating the content out for both of these jobs. Maybe in our process, we could create 1. the component page content and 2. component development guidance (which isn’t displayed in PJs).
Example from @pedroms:
Two different kinds of info in the same Specifications section of https://design.gitlab.com/components/accordion:
- Usage guidance: Just like modals, the header of an accordion could be a question or a title. Either way, headers should give context about the underlying content in a concise and actionable way.
- Development guidance: The icon should always reflect the state of the accordion (expanded or collapsed). The following icons should be used…
But guidance for the implementation is unnecessary once the component is built and styled according to the visual and interaction specs.
Should development/implementation guidance should be temporary or permanent? Where should it be captured/stored?
Solution
- Usage guidance (both for designers and developers) is permanent and lives in PJs component pages
- Development/implementation guidance should live within issues and not shown in PJs component pages
- PJs component pages could potentially link back to Issue which contains development/implementation guidance