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 gitlab-org/gitlab-design#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 inconsistency in how component usage guidelines are written.
Idea
“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 demos and 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. | All |
Design tool component | When using a component, | I want a representation of that component in Figma/Sketch | so that I can quickly work with it in my designs | Designer |
Detailed usage guidance | When using a component, | I want to understand details of variations, style, functionality and accessibility | so that I 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 | All |
Design decisions | When using a component, | I want to understand how research, discussions & usage helped decide 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 |
design.gitlab, GitLab-ui & figma/sketch sync | When using a component, | I want to be sure that the component variations, style, additional functionality and accessibility in design.gitlab reflect what is shown in gitlab-ui and figma/sketch | so that I have an accurate representation of what's available and continuity of understanding with other roles in my team | All |
Add/edit component | When reviewing PJs and I see missing/incorrect component content | I would like to add/edit content | so that I contribute to refining our design system | Designer |
Integrating component | When I am integrating a component in our component lifecycle | I want to ... | so that ... | Developers |
Process
- 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
Additional ideas
- On page table of contents
- Additional tabs
- Changing structure of pages to front-load demos and visual content at top of page
- First step would be changing component template file: https://gitlab.com/gitlab-org/gitlab-services/design.gitlab.com/-/blob/master/pages/components/template.md
Proposal
- Determine a new structure that allows users to easily find the content they are looking for. The end result of this issue should be working page templates and consistent sections and language.