Split up UI Component Readmes

[jffng]

Description
Many UI Component README's contain a lot of information related to differing aspects of the component's use, i.e. both design and development guidelines. This makes it difficult for adopters to quickly skim and find the information they're looking for.

Examples:

• Button
• Modal
• Notice
• Panel

As a developer making use of a component's docs or readme, I would expect the usage documentation to be immediately presented and skimmable.

Suggestion
What if we split up the readme's so that extended design guidelines live separate from the main component readme?

To support the handbook, this would involve a small change to the doc generation script which I'd be happy to take a look at, depending on how folks feel about the suggestion.

[chrisvanpatten]

I think the component documentation is an area where we are really up against the limits of what the WordPress.org handbooks can provide. I know @mtias has a lot of ideas around more generally improving the component documentation experience as well.

That said, I think this could definitely be interesting as an interim step. I’d love to see (as a draft PR or in a SEO are repo or whatever) how you would visualise the separation. Would the primary readme link out to other documentation? Is it about a better structure? I think everyone would be open to improvements in this documentation, and having a prototype would be a great way to proceed.

[jffng]

I think everyone would be open to improvements in this documentation, and having a prototype would be a great way to proceed.

👍

how you would visualise the separation

As an interim step, any of the component docs containing explicit "design guidelines" could contain a separate markdown (e.g. 'DESIGN.md') that lived in the same folder. Here's a rough draft on how the button component could break out and still support the handbook doc generation: master...jffng:try/breakup-component-readmes

Would the primary readme link out to other documentation?

I think the primary readme should contain developer usage documentation: a code example, props, related components, and a link to a design readme or other design documentation e.g. a public Figma.

Is it about a better structure?

Separating the concerns of design versus dev readmes I think would make it easier to both consume and contribute to the docs.

[davewhitley]

I agree with many of the ideas presented here. Now that we have more expanded guidelines for many components it makes sense to split them up.

• CODE.md: The default readme shown. Contains code snippets, usage examples, and props.
• DESIGN.md: Currently, everything under the "Design Guidelines" section of our component docs.
• ACCESSIBILITY.md?: Underdeveloped right now, but more a11y guidelines will be added in the future.

[mtias]

I would be a bit cautious with adding structural separation before we see how the presentation is going to work (#16953), how much written verbosity is going to be included and how much dynamic capabilities are going to be instrumented (for example, "design linting" could be built into the preview, with guidelines being showed in context to the usage, etc).

[DaisyOlsen]

@jffng Any thoughts on whether or not this is still valid?