Improving the UI documentation

Development
,
1

Hello,

The UI part of the foreman is growing and getting more reusable blocks but when it comes to documentation we actually failing.
I think there are tons of missing documentation and the “developers-handbook” don’t feel like a good place for it.

My Proposal:

Extend the storybook we are already “using”, and make it as our main UI documentation, examples, tutorials…
There are tons of well done storybooks, i particularly like the one wix made:
https://wix-wix-style-react.surge.sh

I think we can use the storybook engine for much more than just showcasing react components.

  1. Deploy the storybook as part of the CI

  2. Add .md file based toturials/docs into the storybook

  3. Integrate ESdocs into the storybook to extract docs comments from the source code

I believe the main benefit is to keep the docs as close as possible to the code itself.

1 Like
2

I’m all for interactive docs (I’ve been playing with Jupyter notebooks recently too, very nice…). However, does this work on a statically deployed Jekyll site? Or does it require server-side stuff?

3

This does make sense to me, but the developer handbook should tell you how to get the storybook running so it’s still the source to start with.

1 Like
4

Good point @Gwmngilfen, it’s 100% static and can be easily deploy to gh-pages

Actually, patternfly-react are deploying their storybook to rawgit:
https://rawgit.com/patternfly/patternfly-react/gh-pages/index.html

5

Yes!

It should explain how to run it and how to maintain it. And it may link to a deployed version of the storybook.

1 Like
6

+1 to storybook similar to wix and pf-react linked from the developer handbook. We should definitely have it deployed somewhere.

7

I totally agree with that. It’s much easier to change (and enforce the change) in one PR.

I like the wix storybook style too. If we manage to get the storybook to load .md files then it’s IMHO a win.
Everything you suggest makes a lot of sense to me.

8

I agree that we should use storybook as the documentation on how to use our components. I also agree that we should link to it from the developer’s handbook.

Thanks for taking the time to write this up.