Component documentation

[janchild]

This epic is for the design work associated with improving our component usage documentation.

Goals

The goals of this work are to:

1. elevate the component documentation to a level of excellence
2. set up systems for future maintenance and governance of the content

Phases

The first phase answers the questions:

• What sections do we include in component documentation?
• What are the content requirements for each section?
• What are the minimum parts to a complete component?
• What is the definition of done?
• What are the content gates to releasing a component?
• What is the relationship between components and patterns?

In the second phase, we'll define checklists and work processes to ensure that releases are appropriately gated by complete content.

Work to be done

First sprint

• Assessment of requirements for a component to be complete
  • What sections do we include in component documentation?
  • What are the content requirements for each section?
• Audit of design systems, as needed
• Content guidelines at component level, defined
• Review the relationship between components and patterns
• Check in with Devs, Matt—Anything missing? Anything different needed?

Deliverable: Component template

Second and third sprints

• Update the Support Q&A audit results to present
• Mapping to new template, assessment of existing components
  • Identify gaps in content
  • Identify adjustments to content structure
  • Support Q&A content to be incorporated across pages
• Write up issues for each component, detailing the work in checklists
• Review usage images:
  • Pepper in contextual images
  • Review usage image
  • Review for mentions of pixels versus tokens

Deliverable: Issues written for existing components with all work to be done documented

To be scheduled / scoped / parallel work

• Production guidelines: explanation of work coming from Jeannie
• Kit work to support new images (start small)
• Accessibility section:
  • Any quick wins? How do we make it understandable?
  • Checklist of requirements to be accessible
  • How do we handle it with our tabs?

Subsequent sprints

• Identify a process of design working with dev on these issues
  • How does readme documentation work and fold into this?
  • Devs: how do they want to work with their issues?
• Reorganizing existing content into new format
• Organize the work to start filling in the gaps, break into more issues as required
• Incorporating the variant switcher
• Adding a Feedback section (see Fabric and Github)
• Search Carbon channels to see if questions have been asked and documented
• Analytics assessment
• Review presentation/Ordering of content in tabs
• Style tabs:
  • Motion section
  • Grid layout
  • Theme switcher
• Component status page (last time updated, criteria, accessibility status)
• Review ordering of content in tabs