Documentation for structural patterns

[jgiardino]

When new UI components are added to patternfly-react, we will usually reference documentation that exists somewhere else (e.g. patternfly.org, react bootstrap, etc...) that explains when/why/how to use the UI component.

But in the case of structural patterns, like #256 and #268, is it obvious to consumers what approach they should take? Are there ways that we can document when/how a consumer would use a structural pattern?

[jgiardino]

@jeff-phillips-18 @priley86 @cdcabrera Would you review and provide any comments or suggestions on this? I'm not sure what else I should capture.

[cdcabrera]

Can do on the review... Immediate list can think of, in addition to anything the PRs may/may not already provide

• Expanding the PR Github template may help
• Think you, @jgiardino , and @priley86 mentioned something along the lines of Storybook additions

[jgiardino]

Think you, @jgiardino , and @priley86 mentioned something along the lines of Storybook additions

I created this other issue #304 to handle reorganizing the storybook examples, if that's what you're referring to.

We discussed splitting the structural patterns from the UI patterns, but when I look at some of storybook examples for structural patterns like #256, isn't obvious to me how they would be split out.

[glekner]

+1 on this, on the Notification Drawer aswell, we need to give an example of the data that the drawer wrappers expect, it's not shown right now on the storybook.

[mturley]

It would be nice to have a better site for documentation of components and their propTypes, or maybe Storybook could be turned into this site. It is a little annoying that all the important info (At least in the case of my VerticalNav and WizardPattern) is hidden behind a tiny "Show Info" button in the corner that is easy to miss.

A good example of something that might be more useful is the Grommet docs site (disclosure: I worked on this at my last company), e.g. http://grommet.io/docs/accordion. A small inline example of the component with full interaction enabled, followed by a clear description of the propTypes, and then an "Examples" button with variants of code examples. In their examples page, it starts to resemble storybook (there are knobs, and there is a button to see corresponding code). Perhaps if we had a documentation site it could just link to Storybook for the examples piece.

Definitely room for improvement, but I'm not exactly sure what would work best.

[priley86]

i agree w/ this sentiment and would be OK with gravitating away from Storybook in the long run (someone pitched the idea of following a similar path to PF Next and using Gatsby). It would be great to have a similar skeleton, but I guess as long as the documentation hierarchy follows a similar path, we have options. The Storybook community is doing a lot in the way of improving the core template w/ SBNext though currently: https://github.com/storybooks/SBNext

As far as hierarchy goes, i think it probably makes sense to start following the design documentation 1 to 1, as closely as possible (as well as component terminology w/ components/patterns/layouts). My thought is - we'd be able to build stateless components that line up 1:1 with the BEM classed DOM, and then build our React abstractions/helpers on top of those. This would include things like React HoCs (both recompose HoCs and HoCs we self implement, controlled components, managers, helpers and variations of patterns/layouts, etc). Maybe we categorize those as something else (the word "pattern" is being overloaded now by PF Next). Maybe we call them "compositions"?

thoughts? what other workspace templates are we not considering? I will have to give grommet a look...

[priley86]

i'd also love to think that a new category would apply for canvas type components in the very distant future...but i'm not going to go there right now 😉

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.