Hey, someone from the Storybook team here. We'd love to get actionable feedback about Storybook for documentation. Why is it so much worse that what you're used to? Can you be specific?

Hey there! I just say this as an anecdote of someone who has been a consumer of two teams that use Storybook, so I have not used Storybook myself.

That said, the biggest problem I've had is the "living code samples". I'm not sure of the exact name, but the feature where you display a component on the page and click the Show Code button to do a flip and see the code that drives it. The libraries we use that use Storybook are fairly complex, so I'm not sure how much that has something to do with it, but not a single "living code sample" has been a self-contained example.

When I look at code samples for libraries, I expect I should be able to more or less copy/paste the code directly into my application and it should just work (once the dependencies are added). This includes things like import statements as well so I know where things are being imported from in the case of multiple import paths for a library. Unfortunately, instead it's been lots of wrappers and helper functions in the storybook examples and I've only gotten vague answers of "storybook limitations" as to why they're not totally self-contained copy-and-paste-able.

I'll see if I can speak with one of the engineers at work to ask more about the limitations he meant when I complained about the examples not being self-contained and get back to you on that.

I hope this makes sense and is actually helpful!

Storybook as an official documentation tool is a fairly new idea. They added Storybook Docs pretty recently, which is basically stories that can be written in MDX. It also enables you to document a component's props among other things. IMO, Storybook Docs is on the right path and will become a great documentation tool.

But just using straight up Storybook as documentation, I agree that isn't very good. Whenever I'm just given a random Storybook, my success with that library has been pretty low.

Styleguidist works way better for docs since it’s markdown based and can render numerous “stories” in one page. I find a lot of teams that use storybook end up using features like “knobs” that also require manual interaction. In styleguidist most users just render the components with each possible permutations of props they want to test

This is totally possible with Storybook Docs. It also supports markdown (MDX).