UI Docs - renovation

[KaiVandivier]

I think there are are some great ways the UI library documentation can be improved, mostly by taking advantage of the newer Storybook features.

Here's a write-up on what I have in mind: Google doc - feel free to share your feedback! :)

[ghost]

Looks great! I have feedback that's more general thoughts than specific feedback, so I'll post it here if that's ok:

• About the jsx plugin. I think we can drop this in favor of the plugins created by the storybook team that do the same but better. The non-storybook created jsx plugin has caused several problems in the past.
• One thing that I find important to incorporate in the docs, is the ability to document recipes for usecases composing multiple components, or just recipes for more specific usecases of a single component. We often get questions about how to do something, or requests for components or features, which could be easily remedied by recipes that demonstrate these usecases. If we make them easy to find and copy, I think it would really reduce the maintenance burden. It would also demonstrate to users how we expect the components to be used, I think there's (understandably) often miscommunication between the maintainers and the users about that.
• One important reason for moving away from the jsdoc comments for me personally is also that we have a single source of truth for our component API docs. I keep finding errors in our jsdocs because we forgot to update them, and because they're not enforced/tested.
• About the chromatic & unit tests: I really like those. One thing I often hear about is testing with the examples from your docs, so that you always know that what's in your docs also actually works. And visual tests would be awesome, could replace a lot of our current tests and simplify them. Maybe chromatic wants to sponsor us?
• Maybe before we move ahead with the more elaborate changes, we could pick a couple of components and move those through the intended changes, to see what the result would be. Would make it easier to catch any unforeseen consequences and allow us to judge the end result.
• I'd maybe move Organize components into easily-browsable sections under the Easiest section to Larger Projects. I think this could easily end up becoming a larger task. Since bundling components into sections might raise questions about introductions we need to add explaining the organisation, refactoring some existing examples a bit to fit better, thinking about the link with the design system, etc. Seems like a task that needs more time to clearly define all the steps.

(I'll add the above as a single comment for simplicity. If any point warrants further discussion, feel free to quote it in a new comment so that we can discuss that specific topic in its own thread.)

[KaiVandivier]

Thanks for the thoughtful comments!

1. Agreed about JSX
2. Great point, I agree - This might be relevant about composing multiple components like <Menu> and <MenuItem>: 'Stories for multiple components'. Having the option to make stories out of MDX is also useful - sometimes some longer textual explanations and sample code blocks may be useful for those kinds of components. A complex component like the OrganisationUnitTree might warrant this kind of treatment
3. Noted
4. Nice to hear support for it, I'm interested to hear what others think as well :) this would definitely be a "larger project"
5. Great idea - I'm working a little bit on that right now. A few quirks have indeed popped up
6. Fair enough :) I might also see if I can draft an example organization for review to help that process

[ghost]

Sounds good! 👍

[KaiVandivier]

Hey @ismay, here's what I have in mind for the organization -- I hope a google doc is okay to comment on :)

[ghost]

Sure, no problem 👍! Looks good! Also, I guess that if we want to change it later on it shouldn't be too much effort to change the organisation right? That also kind of takes off the pressure and means we don't necessarily have to get it completely right the first try.

[KaiVandivier]

Yeah totally, it should be very easy to change 🙂 thanks for taking a look!