PJs component page template: re-evaluate content based on JTBDs
Overview
Let's re-evaluate the content (and structure) of the PJs component page template to improve the utility and usability for GitLab designers, devs and PMs. This is related to the broader PJs information architecture challenges mentioned in #798 (moved).
The best way to prioritise, manage and refine the content on the page is by using Jobs to be done.
Problem
The main pain points I found with component page templates today:
- Text-heavy - PJs is much more text-heavy than most other design systems. Much of the text content could be replaced with images and demos. The large amount of content makes it hard to scan and find the information I'm looking for.
- Usage guidance vs implementation guidance - Content on implementation guidance (as discussed here) is left in the usage guidelines - adding to the text-heaviness. This also reduces the clarity on the usage guidance in general.
- Burying the lead - The current structure is setting pages up in a way where the demo is at the bottom of the page behind a bunch of text which may or may not be relevant for your use case. A new structure is required which front loads the demo and dives into details later. Following similar ideas to the Minto Principle.
- Additional content - We also have a lot of other content that could be interesting to include in a design system as stated in this comment - this doesn't need to be shown on the page, but could at least be linked, so we see the thought and rationale that has gone into designing the component
- Variation - There a lot of variability in how component usage guidelines are written - making component guidelines inconsistent.
There is a bunch of functionality in Storybook which is causing our devs to ignore PJs for now
Solution
“If a picture is worth a thousand words, a prototype is worth a thousand meetings” - David Kelley, IDEO
Some general principles for laying out these pages:
- JTBD & role-informed - We should differentiate sections and prioritise what content goes on the page based on what our primary personas are trying to achieve
- Demo-heavy - We should front-load our component pages with visual content and demos for a quicker understanding
- Show me > tell me - We should strip away as much text as possible in favour of programmatically embedding rules, styles and interactions
- On-page nav - We should have on-page navigation for quicker access to particular sections
- Standardise component usage sub-sections - We should standardise on component usage sub-sections to improve consistency and clarity (e.g.IBM carbon standardized on component variations, content guidelines & interactions/functionality). This also makes it easier to spot whether any functionality or styles are missing.
I think IBM Carbon and Salesforce Lightning are both great examples of prioritising which JTBD they want to satisfy for designers & devs without being too text-heavy.
Jobs to be done
Create a ranked list of JTBD to prioritise content on the page:
Title | Situation | Motivation | Desired outcome | Persona |
---|---|---|---|---|
General usage guidance | When I am unfamiliar with a component, | I want a quick and high-level overview of the what the component looks like, how it works and its most popular use cases, | so that I know whether or not I should use it. | Designer |
Design tool component | When using a component, | I want a representation of that component in Figma/Sketch | so that I work with it in my designs | Designer |
Detailed usage guidance | When using a component, | I want to understand details of variations, style, additional functionality and accessibility | so that I can get use the component in the way it was designed | Designer |
Component usage in the product | When using a component, | I want to where else in the product it is being used, how much it is being used and for what use cases, | so that I | Designer |
Component research | When using a component, | I want to understand what research has informed this component's design | so that I have more context around how the component was designed | Designer |
Design decisions | When using a component, | I want to understand how we decided on a specific design, tenet or guideline | so that I understand why the component was designed in that way | Designer |
Component gaps | When using a component, | I want to understand whether this current iteration of the component has the variations, style, additional functionality and accessibility required for my use case | so that I know whether we should update it or not | Designer |
Component pipeline | When using a component, | I want to see if there are any new components or updates in the pipeline | so that I can utilise the component or collaborate with the person who is working on it | Designer |
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. | Developer |
Next steps
- Gather - Use this issue to collate what the primary the JTBD for designers, devs, PMs, technical writers, researchers
- Prioritise - Prioritise the JTBD to prioritise the content in PJs
- Create template - Create a new content template based on our prioritisation
- Create vision mockup - Create a new vision mockup of what PJs component pages could be