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 💫

• Finalize and implement a template for documenting components. @mattrwalker
• 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.

[mirka]

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.

[mirka]

@auareyou I have a draft PR at #66617 so you can start reviewing/authoring the content for Button there.

[auareyou]

Thank you, @mirka; I have content I could start adding soon.

[auareyou]

Closing this issue as completed.