Storybook: Best practices for getting the most out of StoryBook?

[tomspeak]

I would be interested in hearing about how people are setting up their storybooks.

I have been approaching it by mostly making one view for each component, then building up documentation, examples, and variations there.

import * as StoryBook from '../../../storybook/';
import * as React from 'react';
import { storiesOf } from '@storybook/react';
import T from '../';

const Story = () => {
  return (
    <React.Fragment>
      <StoryBook.Intro title="Typography">
        <T.Text>
           Hello World
        </T.Text>
      </StoryBook.Intro>

      <StoryBook.Import>import T from '@common/Typography';</StoryBook.Import>

      <T.Text>
        All typography components implement a <T.Text mono>`BaseTypography`</T.Text> mixin. This allows all components
        to have a base level of customisation.
      </T.Text>

      <T.Header1>Text</T.Header1>
      <T.Text xlarge>{text('Xlarge', 'I am an xlarge text component')}</T.Text>
      <T.Text large>{text('Large', 'I am a large text component')}</T.Text>
      <T.Text>{text('Text', 'I am a standard text component')}</T.Text>
      <T.Text small>{text('Small', 'I am a small text component')}</T.Text>
      <T.Text mono>{text('Mono', 'I am a monospaced text component')}</T.Text>
    </React.Fragment>
  );
};

storiesOf('Styling|Typography', module)
  .addDecorator(withKnobs)
  .add('Default', () => <Story />);

I believe this is a better user experience, but I find myself fighting a lot of the tools. Take for example, my approach above, it means that add-ons like the JSX viewer, actions and so forth either do not work or are noisy/not useful.

Before I double down on fighting against StoryBook to have it work more like documentation than presenting components individually, what are other people doing? Will I be fighting a losing battle?

Thanks

[shilman]

This is a longer discussion, but here's my quick take:

https://www.learnstorybook.com/ covers a lot of best practices about writing stories to capture and test the key states of your components.

As for using Storybook as a documentation tool, I agree that it should be a lot better. There are a ton of different addons right now, but like you said it's kind of a patchwork and they leave a lot to be desired. To address this we're building Storybook Docs, a series of updates to Storybook that will help you turn your stories into world-class documentation.

My suggestion: focus on capturing the useful states of your UI in stories, and starting in 5.1 you'll have much better options on the documentation front. I've set up a discussion channel #docs-mode in the Storybook Discord if you're interested in participating in that effort.

[tomspeak]

@shilman - thanks for this. Is there a rough timeline for 5.1? Want to see if it's potentially worth holding out for 5.1, or getting value out of my current approach before 5.1 arrives.

[shilman]

@tomspeak Putting together a plan as we speak. We'll definitely have something you can use in April, tho the exact 5.1 release date is TBD. That said, 5.1 won't be a full solution either. We're carefully building this up to make it compatible with the thousands of storybooks that are already out there.

If you do decide to roll it yourself (which is cool!), my biggest advice is to try to keep your stories as coherent individual component states / use cases and not try to cram documentation INSIDE the story as you've done above. Instead, annotate the story with decorators / wrappers / parameters (however you want to do it). We'll definitely be building Storybook Docs to work best with these isolated stories, and if you choose to write your stories with embedded docs, your mileage may vary.

[CodeByAlex]

@tomspeak, in the interim you could also use the notes addon and add your documentation there. That is what I am doing at the moment. I set the notes to a markdown file located in the same directory. This keeps documentation out of the config but still available for each component since the notes tab changes when the component changes.

[shilman]

Good call @CodeByAlex. @ndelangen and I are currently prototyping docs features as extensions to the notes addon, so it's probably a safe bet that there will be a useful migration path from today's notes to tomorrow's Storybook Docs.

[tomspeak]

Thanks a lot everyone. In the mean time we're going to switch to notes, and set ourselves up for success with the new docs API.

[stale[bot]]

Hi everyone! Seems like there hasn't been much going on in this issue lately. If there are still questions, comments, or bugs, please feel free to continue the discussion. Unfortunately, we don't have time to get to every issue. We are always open to contributions so please send us a pull request if you would like to help. Inactive issues will be closed after 30 days. Thanks!

[stale[bot]]

Hey there, it's me again! I am going close this issue to help our maintainers focus on the current development roadmap instead. If the issue mentioned is still a concern, please open a new ticket and mention this old one. Cheers and thanks for using Storybook!