Design guidance documentation audit

[auareyou]

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?

[auareyou]

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.

[jameskoster]

Just to clarify, what does the end result look like? I'm curious about the roles each channel plays:

1. Readme file in components package
2. developer.wordpress.org
3. 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.