WordPress
Design guidance documentation audit
Overview
This is an audit of all the design guidance for the WordPress design system components. This is part of a joint effort to understand and audit the current system at a higher level.
Goal 🎯
Make sense of the state of our design guidance across our different reference sites and recommend a path forward to state-of-the-art documentation for designers and developers.
Definition of done 💫
- [x] Finalize and implement a template for documenting components. @mattrwalker
- [x] Complete a comprehensive component inventory.(@mattrwalker @mirka and @jameskoster)
- [ ] Assess the existing level for each component.
- [ ] Develop and agree on a clear action plan based on the recommendations.
- [ ] Approve and prioritize the next batch of work for execution
What we're evaluating 🗒️
| Criteria | Description |
|---|---|
| Accuracy | Is the information relevant, true, and up-to-date? |
| Clarity | Is the information easy to understand? |
| Consistency | Does the content sound uniform and consistent in tone? |
| Visual examples | Do/which components have visual examples and code snippets? |
Additionally, we’ll be assessing comprehensiveness. In the next version, a component has enough design guidance it includes the following sections:
| Sections | Description |
|---|---|
| Introduction | Does it have an introduction describing what the component is for? |
| Best practices | Does it have rules or methods for using the component effectively? |
| Do’s and don’ts | Does it outline appropriate and inappropriate behaviors or actions in particular situations? |
Components to document this cycle
Button
https://developer.wordpress.org/block-editor/reference-guides/components/button/
This component is fully documented and it just needs editing and updated visual examples.
Modal
https://developer.wordpress.org/block-editor/reference-guides/components/modal/
The documentation is also pretty complete, could be another good candidate.
Just to clarify, what does the end result look like? I'm curious about the roles each channel plays:
- Readme file in components package
- developer.wordpress.org
- Storybook
My understanding is that the readme's and developer.wp are connected, but both seem inferior compared with Storybook by virtue of the control panel/live preview.
Should the Storybook pages 'replace' the developer.wp.org pages? I notice that some of them are already directing visitors to Storybook.
It seems like a lot of potentially duplicated effort to maintain readme's and Storybook.
It seems like a lot of potentially duplicated effort to maintain readme's and Storybook.
Right. I have recently set up a readme auto-generator (#66035) so the README.md files won't have to be maintained by hand. The readme for AlignmentMatrixControl is an example of the auto-generator in action — the main purpose of these auto-generated pages being to provide barebones docs and nudge more people towards the Storybook. It's only live on two components right now, but I'll continue to enable the auto-generator on the rest of the components.
Button is probably a good place to start. @auareyou I'll coordinate with you to set up where/how the new docs should be authored, since the README.md file will soon be converted to an auto-generated version and thus cannot be edited directly.
@auareyou I have a draft PR at #66617 so you can start reviewing/authoring the content for Button there.