Documentation Reorganization Project

[jonniebigodes]

I created this issue as a means to coordinate with the community on what aspects of documentation are still missing or undocumented.

How to help

If you're interested in sharing feedback based on the current documentation, we'd love to hear your thoughts! Leave a comment below so that we can coordinate our efforts and present the documentation in a more streamlined way.

Thank you in advance for the feedback and for being part of the community!

Stay safe all

[K-Schaeffer-LOG]

I'm including Storybook as a tool to doc our design system here at LogComex and I noticed that there's just a few Vue snippets and examples, most of them are in React.

I think It would be nice to include more Vue examples, and I'm interested to contribute with it in a near future.

[jonniebigodes]

@kauanschaeffer that's awesome to hear, glad that you're incorporating Storybook in your design system. Me and one other contributor have pushed the missing snippets for Vue in #13510 and #13498. For examples purposes let us know what type of examples you want to see featured and we'll take it from there. Also if you're ok, when you have the chance to fully integrate Storybook let us know and we'll add it to the list of examples here.

Stay safe

[sarahbethfederman]

I have a lot to add here but I'm currently organizing my thoughts :) My biggest piece of feedback is that the paragraph and example focused format makes it really hard to find information you're looking for, and leaves a lot of things undocumented. The lack of comprehensive documentation on DocBlocks is pretty big too. Will update later this week with more specific info!

[jonniebigodes]

@sarahbethfederman the DocBlocks portion is high on my todo list. I'm working still working on it. Looking forward for your specific information.

[kaelig]

Moving #13584 here 👇

---

Is your feature request related to a problem? Please describe
When building addons, adding decorators, or toolbars… I always feel like I need to look at Storybook's source or look for how other people have solved it in their projects.

Describe the solution you'd like
I'd love to have a technical reference that's very thorough and also contains all types available publicly. Something like TypeDoc would be great (it doesn't have to be pretty, just thorough).

Are you able to assist to bring the feature to reality?
I'm happy to review pull requests!

[reno1979]

Great news!

I also noticed I had to view a lot of examples to find some of the possible parameters / options.

I needed the examples for the possible files and their content inside the storybook folder, the possible params for docs and controls (controls type tables where a big help though)

Some advanced examples perhaps, for example how to hook into the refresh event on file change, to start some own build or terminal scripts.

And of course the examples. (I hope vanilla web components will get supported)

[Vadorequest]

From #13636

I'm haveing a hard time with argTypes. I waste a lot of time going through the documentation when I try to do things.

For instance, I wanted to disable a property, I tried:

// Worked but I lost the field in the doc and I don't want that
export default {
  title: 'Next Right Now/Form/Btn',
  component: Btn,
  argTypes: {
    children: {
      table: {
        disable: true,
      },
    },
  }
} as Meta;

// Didn't work
export default {
  title: 'Next Right Now/Form/Btn',
  component: Btn,
  argTypes: {
    children: {
      canvas: {
        disable: true,
      },
    },
  }
} as Meta;

// Didn't work
export default {
  title: 'Next Right Now/Form/Btn',
  component: Btn,
  argTypes: {
    /**
     * @readonly
     */
    children: {},
  }
} as Meta;

// Worked and does exactly what I wanted
export default {
  title: 'Next Right Now/Form/Btn',
  component: Btn,
  argTypes: {
    children: {
      control: {
        disable: true,
      },
    },
  }
} as Meta;

Is there a single source of truth regarding all options in argTypes? It might be complicated due to all the addons having their own property, but an extensive summary would be very user-friendly.

[Vadorequest]

I'm going to use this post to centralize the documentation gaps I've found myself based on all the things I haven't found in the doc (as a new Storybook user from 3 days ago who's read most of the documentation), if that's alright with you. I believe it helps the purpose of this issue.

Something that could be documented for React users:

• children is particular and I advise to disable it for all stories by default in preview.js:parameters as I did in UnlyEd/next-right-now@d8a5d8e, it could be a good React advice. Although, I wasn't able to re-enable it on a component/story level. (but that's might be a bug rather than a documentation issue)
• It's very hard to understand what are the JSDoc @ that are being used to generate the doc. So far I've found @default to be the only one that's useful. Other @, like @see are being ignored. I couldn't find any relevant documentation despite searching on both the doc and the typescript babel plugin. Also, I believe the default behavior shouldn't be to ignore @see documentation, I'm not sure why it does that. It's be nice to be able to decide what to do with each @, one a case-by-case basis. (but that's probably a feature request)
• I couldn't find best practices for when we need to add a "Story props", which doesn't exist in the Component itself, but serves the purpose of the Story. For instance, when mocking children, I usually use a text props, but it's only meant to make the story controllable (Controls), and should be marked as abstract or similar as it doesn't really exist.
• It's hard to figure out how to describe a property, it can be done in the property itself, but also on the arg or argTypes on the Story? I'm not sure, but I felt like I was lacking an overview on how to describe a Component/property properly, I feel like there are many ways and I know so few.