Hey! Storybook evolves everyday and it's clear a lot of hard work is being put in 👏 The thing is, you guys are so productive and things change so fast (both code- and governance-wise) that I can't always keep up. Catching up is not much of a problem and definitely not something I'm afraid of :')
However, whenever I want to contribute, I want to make sure I'm doing things right! I don't want to miss any kind of steps (e.g. RFCs) and often end up re-reading the whole contribution guidelines. Those are really helpful and important but I feel like at the moment, they have two main issues: improvable discoverability and mildly frustrating navigation.
Discoverability
Without bookmarking it, there's no quick access to the latest contributing guide. As a contributor, I'm used to quickly find it through either the website or the repo's README/CONTRIBUTING.md. That's indeed the case but it ain't as straightforward as I would expect:
From the repo
(okay this is probably a bit off-topic since we're not on the core repo)
There's a whole "contributing" section in the README.md that includes a link to the CONTRIBUTING.md, which itself includes information and eventually redirects to the actual new contributing guide. The dedicated section in the README.md seems right, but:
shouldn't it link directly to the new contributing guide?
if so, is this middle CONTRIBUTING.md file still needed? (maybe as part of the community health files) [b]
if still needed, shouldn't it ONLY link to the actual contributing guide to enforce a "single source of truth" [a]
From the website
There is no direct link to the contributing guide on the front page, which is neither surprising or absurd since it may be considered "secondary", although I'd definitely imagine such a link inside the footer under either the "docs" or "community" category. So we're left with two ways of accessing the contributing guide:
Using the searchbar, but algolia is being… algolia!
Going to the docs page and then either search for "Contribute" or scroll down the sky-scraping sidebar until I find it.
Navigation
Well now that I've exercised and beefed up my index finger scrolling the whole sidebar, I can read the whole contributing guide, starting with the index page "How to contribute" which then redirects to different "ways to contribute". Handy because one can easily access resources depending on the type of intended contribution, But I still want to read through the whole guide, page by page.
No issue when solely using the sidebar to jump from one page to another, but things get pretty annoying when clicking any internal link from the docs as they hard-redirect and therefore cause the sidebar's scroll position to be lost. It's especially easy to be fooled with the recurring "Learn more about contributing to Storybook" section in the whole Contribute part.
Some ideas
Docs' internal links should act like route changes and not hard redirects (cf. previous paragraph)
Maybe the docs should include a shortcut to the contributing guide?
Maybe the contributing guide should have its dedicated space on the website?
(as an alternative, the "contribute" link could be inside the footer if it feels too intrusive inside the header)
Hey! Storybook evolves everyday and it's clear a lot of hard work is being put in 👏 The thing is, you guys are so productive and things change so fast (both code- and governance-wise) that I can't always keep up. Catching up is not much of a problem and definitely not something I'm afraid of :')
However, whenever I want to contribute, I want to make sure I'm doing things right! I don't want to miss any kind of steps (e.g. RFCs) and often end up re-reading the whole contribution guidelines. Those are really helpful and important but I feel like at the moment, they have two main issues: improvable discoverability and mildly frustrating navigation.
Discoverability
Without bookmarking it, there's no quick access to the latest contributing guide. As a contributor, I'm used to quickly find it through either the website or the repo's
README/CONTRIBUTING.md. That's indeed the case but it ain't as straightforward as I would expect:From the repo
(okay this is probably a bit off-topic since we're not on the core repo)
There's a whole "contributing" section in the
README.mdthat includes a link to theCONTRIBUTING.md, which itself includes information and eventually redirects to the actual new contributing guide. The dedicated section in theREADME.mdseems right, but:CONTRIBUTING.mdfile still needed? (maybe as part of the community health files) [b]From the website
There is no direct link to the contributing guide on the front page, which is neither surprising or absurd since it may be considered "secondary", although I'd definitely imagine such a link inside the footer under either the "docs" or "community" category. So we're left with two ways of accessing the contributing guide:
Navigation
Well now that I've exercised and beefed up my index finger scrolling the whole sidebar, I can read the whole contributing guide, starting with the index page "How to contribute" which then redirects to different "ways to contribute". Handy because one can easily access resources depending on the type of intended contribution, But I still want to read through the whole guide, page by page.
No issue when solely using the sidebar to jump from one page to another, but things get pretty annoying when clicking any internal link from the docs as they hard-redirect and therefore cause the sidebar's scroll position to be lost. It's especially easy to be fooled with the recurring "Learn more about contributing to Storybook" section in the whole Contribute part.
Some ideas
Docs' internal links should act like route changes and not hard redirects (cf. previous paragraph)
Maybe the docs should include a shortcut to the contributing guide?
Maybe the contributing guide should have its dedicated space on the website? (as an alternative, the "contribute" link could be inside the footer if it feels too intrusive inside the header)
Please let me know what you guys think :)