[RFC] Deprecate Storybook - simplify project to essential components and styles using VuePress

[brylie]

Problem

Consider rebooting this repository as a simple Vue-only app that fulfills the essential requirements.

A cohesive design system & Vue component library to unify the web-facing Creative Commons.

Further, the project is intended to:

[provide] HTML/CSS styles (for sites that don’t have Vue) AND Vue Components in one place. @obulat

Description

I've spent the better part of two days trying to get this project to run. Complexity may be the fundamental issue preventing Storybook from running (#897) or rendering in deployment (#895). In effect, there are too many dependencies of dependencies and some of them may be interacting in unpredictable ways (storybookjs/storybook#14410).

In a moment of reflection, I asked "what is essential about CC vocabulary?". I believe the short answer is "the CSS styles and Vue components are essential."

What is essential?

Several essential qualities have been mentioned so far through discussions:

• Visual presentation - a regular person can hop in, see how we do buttons, etc. @annatuma
• Components - HTML/CSS and Vue components @obulat
• Dependents - down-stream projects: Search, CCOS, and Summit that are running on Vocabulary, each in different forms @annatuma
• Developer experience - It should be very simple for a new developer to start up the project, without getting tangled up in tooling @brylie

Proposal

We can use VuePress as a static documentation tool and development aide for the CC Vocabulary components. There is a tutorial series on using VuePress to document a Vue component library. While the outcome wouldn't be as sophisticated as Storybook, the simplicity and affinity of using VuePress could be a net gain. Further, the VuePress project could be used as the basis for a living CC style guide.

Alternatives

Power through the errors and get Storybook to work. To "power" (force) one's way through difficulties is a reasonable strategy, and one commonly taken with JavaScript development. To a certain extent, large parts of the JavaScript ecosystem may be the result of powering through problems created by solutions to other problems. However, we have the opportunity to reappraise the essence of this project and steer towards an essential architecture.

I don't propose to arbitrarily "throw out the baby with the bathwater", but in this case, the complexity added by Storybook may outweigh its benefits.

Additional context

Looking to component library projects like Quasar and Vuetify, it seems they document their components with their components (eating their own tofu, so to speak.)

Regarding Storybook, @zackkrida makes a reductionist observation that:

Storybook in particular feels disproportionately heavy and complex in comparison to the value it provides.

Vocabulary could fundamentally be a single CSS file.

Implementation

• I would be interested in implementing this feature.

[brylie]

@dhruvkb would you please provide your perspective in this RFC? I appreciate the comments you made in PR #903 and want to make sure we consider them in this context 😃

[dhruvkb]

I'll reiterate some points from this comment and expand on them a little bit.

At the core of my ideas are two points:

• Storybook is a very powerful tool with interactive features that could be very useful to us. Building our own solution would be a lot of work for our small team.
• VuePress is a very simple tool for writing documentation. Using it as a component showcase would require a lot of groundwork.

On the other hand, the issues we have with Storybook stem from the following root causes:

• Three projects, with different toolchains and frameworks each running its own Storybook instance makes maintenance 3x the pain it should be.
• Storybook has a very turbulent development, it has in the past few versions introduced all new formats, extensions and ways to write stories.
• Storybook with all the extensions is sometimes more complicated than our entire library put together.

I suggest keeping Storybook around (for the sole reason that a different team builds and maintains it) while also simplifying our architecture as much as possible to ensure updating Storybook is painless in the future.

• [RFC] rearchitect project to keep separate packages with single Storybook app #905
• Dropping all excessive addons keeping the very minimum
• Writing common stories for Vocabulary and Vue Vocabulary
• Throw away most of the addons make updates easier
• Merge Fonts and Vocabulary into one package

[brylie]

I agree with what you have written. In particular, I share your concerns about the development turbulence and complexity of extensions/dependencies.

On the subject of VuePress, the idea is to create a minimal display/documentation project for our specific Vue components, not to replace all of the functionality of Storybook. See the following resources for an idea of how that might look in practice:

• 📖 Structuring a Vue component library
• 📖 Using VuePress for plugin documentation
• 💻 siegerts / vue-component-library-template

VuePress wouldn't necessarily reduce the number of dependencies perhaps but would share a stronger affinity with our Vue component library than the Storybook/React dependency graph.

[dhruvkb]

@brylie that makes a lot of sense. VuePress is closer to the Vue ecosystem and could be a good way to dogfood Vocabulary to build the Vocabulary showcase. My only concern against it is that if we need more features later, it'll be quite cumbersome and dev-intensive.

[github-actions]

Stale issue message

[brylie]

Closing, as superseded by #905