Pajamas UX Maintainer Checklist
🤔 Reason for this issue
When reviewing Pajamas docs changes, it seems like there's probably a list of recommended things to check for every MR. Each maintainer has their own internal "checklist" of items they look for as they review MRs. It might help trainee maintainers (like myself) to get insight on what each maintainer's personal checklist is, so they have a defined list of things to verify for each review they tackle?
Note: this shouldn't be an actual checklist on each MR, more just a guide of list of things it's "good to check" on Pajamas Docs MRs as you review them.
✅ The list!
-
General guidance:
- Focus your review on content, website user experience and information architecture (IA).
- If you know of any related or similar issues/MRs, note them so we can verify the proposed changes all work together seamlessly.
- It's okay (and preferred) to ask others for help when you don't know something yourself.
- If the updates refer specifically to designs that have been created, double check everything matches what's in Figma.
- Component demos should be used whenever possible. If not possible yet, a TODO should be used instead.
- Related components are listed on each component page (alternative components or components that are usually paired).
- If the status page is being updated, ensure the related content pages match the updated status. (For example,
complete
vue docs should not have the banner that states the component does not conform to pajamas. A separate issue/MR should be created to remove the banner if we are updating the status tocomplete
.Complete
usage docs should also not havetodo
banners.) - Component accessibility:
- Keyboard navigation is documented.
- Text to be read out loud by screen readers is documented.
-
In the copy, ensure:
- There are no grammar or spelling errors.
- Writing follows our [voice and tone guidelines].
- Text follows the [punctuation guidelines]. Don't forget those Oxford commas!
- Headings are correctly nested (top-level headings are
##
) and don’t end with a period or a colon. - Keep an eye on section and paragraph length. Neither should be too short or too long.
-
_Emphasis_
and**strong**
are used sparingly. - Component page structure follows the [documentation guidelines].
- Text is as simple and clear as possible. Everything in Pajamas should be understandable even without additional background information.
- All links work as intended. In addition, if a link is changed in the MR, make sure there are no references to it outside of the diff that also need to be updated. Component references also need to be cross-linked to their respective component pages (for example, mentions of
Alerts
should link to the Alerts component page). - Use
For example
instead ofe.g
. - Avoid using
should
statements. Just tell people what to do instead. - Use full, descriptive sentences so that readers don't have to go back and reference the section title to understand the content within a section. For example, rather than
Use to highlight...
, instead try:Use cross-column colors to highlight...
- Content that is similar or related in meaning is grouped together, if possible.
- Technology or GitLab terms are correctly used.
-
For the MR itself, ensure:
- That at least the first commit message is formatted according to conventional commit standards
- That you review it locally, either through checking out the branch or looking at the review app to ensure the content is formatted appropriately.
Edited by Amelia Bauerly