Information Architecture update - code snippet / API documentation

[ronniemcbride]

Objective

Advance and update the information architecture of ux.redhat.com for designer and developer guidance and development needs.

Request & Considerations

• Add support for code snippets and API documentation
• Add an accessibility section (dedicated page and in the context of each component's page.)
• Reorganize the content architecture and make it more audience-focused (designer, developer, and implementer)
• Each page should be its miniature Single Page Application (SPA)
• Separate component pages into five tabbed sections of focus. (overview, styles, design, usage, accessibility ) by doing so, designers, developers, and implementors should be clear about what information is essential to them.
• Each tab should be a template doc. For example, updates should be independent updates to that section without having to update the entire component page.

- For instance:

elements/ rh-footer/docs/design.njk
elements/ rh-footer/docs/styles.njk
elements/rh-footer/docs/usage.njk
elements/rh-footer/docs/overview.njk
elements/rh-footer/docs/ accessibility.njk

• We need the ability to implement page states. Page states will allow us to link to a particular tab.

[markcaron]

Created an epic for the work needed. We should discuss how to tackle this here, though.

#359

[markcaron]

Also related is @bennypowers' earlier discussion about integrating APIs into docs:
#255

[coreyvickery]

Here's the Google Doc we're working from.

https://docs.google.com/document/d/11ewbiDJ8vG0Xar1hA2XnMuM_4dARGi9sToHm29S4dIw/edit

[coreyvickery]

A discussion about changes to the ux.redhat.com website IA.

Mark Caron
Is the thought that Get Started might house the Designer / Developer sections? I'm wondering if those sections are too robust to be subpages and may warrant a full section of their own

Also, there might be a need for a Contribute section

Steven Spriggs
should contribute be made front and center maybe top right of header bar? links to github etc

Corey Vickery
I could see the child pages under Get started move to a Designer parent section.

Mark Caron
Yeah, I can see that too

Steven Spriggs
I think in some ways we could add separate pieces like that

Git link in the masthead

Landing page could have a "contribute" band of sorts

Should the contribute link go directly to how to contribute documentation in github rather then on ux. itself? Again if we are using that as a starting point for everything?

Mark Caron
Maybe

[marionnegp]

Discussion about nav titles from chat

There was discussion about the proposed component page nav titles: Overview, Styles, Usage, Implementation, Accessibility, Status.

The Usage section would include:

• Anatomy
• When to use
• Configurations or Variants
• Alignment or Placement
• Content or Writing
• Behavior or Actions
• Layout

The Implementation section would include info about:

• Overview
• Installation
• Usage
• Slots
• Attributes
• Methods
• Events
• CSS custom properties
• CSS shadow parts
• Recommendations or Considerations

Benny said that he wasn't sure about implementation and usage because:

"implementation" means "info for developers in order to build this component"; "usage" means "info for developers in order to use this component to build a page or an app"

He preferred to change Usage to Use Case and Implementation to Usage.

Other ideas instead of Implementation or Usage for the dev-focused section:

• Execution
• Code
• Component API

[bennypowers]

Can we make a clear distinction in our new IA between "components" (i.e. web components) and "patterns"? We need to document the design for patterns that we don't and will not implement as web components. To group them all together under "components" (as we do now) is confusing. Some components also have associated patterns ("here's the footer web component, here's the footer pattern") - I think it's OK and even preferable to document those separately

[marionnegp]

I saw that Carbon does this. They have a Notifications component page and Notifications pattern page. Dropping this is as an example.