Storybook: Addon-docs: StoryDescription is not shown for first story

[jonathanherdt]

Describe the bug
For the first story after storiesOf, any storyDescription is not shown.

To Reproduce
Steps to reproduce the behavior:

1. Add a new file button.stories.js
2. Add a storyDescription to the first story (see code snippets below for an example)
3. Take a look at this in storybook in the "Docs" view

Expected behavior
The storyDescription should show, just like it does for any other story.

Code snippets

storiesOf("Button", module)
    .add("vanilla", () => (
        <button>My vanilla button!</button>
    ), {
        docs: {
            storyDescription: `
My button description
            `,
        },
    })

System:
Please paste the results of npx -p @storybook/cli@next sb info here.

Environment Info:

System:
OS: macOS 10.14.6
CPU: (4) x64 Intel(R) Core(TM) i7-7567U CPU @ 3.50GHz
Binaries:
Node: 10.16.0 - ~/.nvm/versions/node/v10.16.0/bin/node
npm: 6.9.0 - ~/.nvm/versions/node/v10.16.0/bin/npm
Browsers:
Chrome: 76.0.3809.132
Safari: 12.1.2
npmPackages:
@storybook/addon-a11y: ^5.2.0 => 5.2.0
@storybook/addon-docs: ^5.2.0 => 5.2.0
@storybook/addon-storysource: ^5.2.0 => 5.2.0
@storybook/addon-viewport: ^5.2.0 => 5.2.0
@storybook/react: ^5.2.0 => 5.2.0

[patelvp]

Hey, absolutely new to contributing to open source community. Can i give this a shot? Have some experience setting up and creating storybooks from scratch. Would be a good challenge that i would like to take on.

[shilman]

@patelvp would be awesome! Lmk if you have q’s

[patelvp]

Was able to find the bug.
In DocsPage.tsx

<>
    <Title slot={titleSlot} />
    <Subtitle slot={subtitleSlot} />
    <Description slot={descriptionSlot} />
    <Primary slot={primarySlot} />
    <Props slot={propsSlot} />
    <Stories slot={storiesSlot} />
  </>

The first story is printed by the Primary component and the rest of the stories are printed with the Stories component.
In primary component DocStory is called as
<DocsStory {...story} expanded={false} withToolbar />
Expanded is set as false here hence it is not printing the title and description.
What was the design decision here. A simple fix is passing expanded as true. @shilman What do you think about this fix? Hopefully it does not break anything else. Will run tests to check that. Opening a PR soon.

[shilman]

That was a design decision, tho now I'm not sure it was the correct one. @domyen WDYT?

[patelvp]

@shilman Might've messed up creating a PR. New to forking and creating a PR. Not sure why there are so many commits on the PR.

[shilman]

@patelvp branch from next and target next in the PR

[patelvp]

@shilman Can you take a look at the PR?
Thanks

[donaldpipowitch]

I don't know... every time I write stories I stumble over this issue. I think it would be nice if Storybook would not emphasize the first story by default. It should be treated like the other stories and there should be a way to write a more general introduction/description unrelated to a specific story, if needed. But just my opinion. It's probably too late to get this into v6?

(Update: Workaround for v6-rc:

import {
  Title,
  Subtitle,
  Description,
  Primary,
  Props,
  Stories,
  PRIMARY_STORY,
} from '@storybook/addon-docs/blocks';
import React from 'react';

export const parameters = {
  docs: {
    page: () => (
      <>
        <Title />
        <Subtitle />
        <Description />
-        <Primary />
        <Props story={PRIMARY_STORY} />
-        <Stories />
+        <Stories includePrimary />
      </>
    ),
  },
};

But I still think it is an UX gotcha. 🤔)

[shilman]

cc @domyen

[domyen]

Apologies for the late reply everyone 🙏. There seem to be two issues here:

StoryDescription is missing from the primary story (the one at the top) of the DocsPage. I agree that this is an oversight. My strawman is to put the description (only) here.

The idea of "Primary" stories
Docs was designed to feature one representative story for each component. This is common practice amongst the design systems we researched like Shopify Polaris, Workday Canvas, and Auth0 Cosmos. But I get that not everyone is going to have the same mental model – that's why DocsPage is fully customizable.

There are a few things we can do here:

1. Document that the first story == primary docs story. We should have done this in the first place! cc @jonniebigodes can we add this to the new 6.0 docs?
2. Allow people to override the primary story without replacing the DocsPage. Perhaps add a primary parameter at the story level.

I don't think it makes sense to eliminate the primary story concept because a use case we'd like to support in 6.0 is live adjusting that story via the ArgsTable. I think this behavior with make the primary distinction make a bit more sense.

[jonniebigodes]

@domyen we can make it work. I'm going to add this to my todo list and i'll circle back to it shortly.

Sounds good?

[patelvp]

I can work on

1. Adding story description between the primary stories and args table
2. Finding a way to allow people to somehow override the primary story behavior

[shilman]

I like this proposal @domyen. i think we can squeeze it in for 6.0 if there's a good PR in the next day or two.

@patelvp people can override the primary story behavior using @donaldpipowitch 's workaround above https://github.com/storybookjs/storybook/issues/8093#issuecomment-665020569

[Mutinix]

@shilman @domyen - There are a couple of thoughts I had regarding this:

1. None of the examples in the Storybook website follow this pattern, including the Tasks example in the official tutorial. If I have a HeaderWithLink and HeaderWithoutLink, there isn't really a primary story. Therefore, I'm not sure if this is the default pattern to follow.
2. At the very least, I don't think we should exclude the primary story from the list of stories that follow below. It seems an odd UX experience to have story #1 on top and (n-1) stories below that.

If the encouraged pattern is to have a BaseButton or BaseHeader configurable story, I think the documentation should encourage that from the beginning. Having said that, my contention is that this should not be the default. I've found the same issues as @donaldpipowitch and it seems unintuitive for most cases.

Thank you!