Design System Documentation is not up to date

[kulmann]

Describe the bug

The design system documentation living at https://owncloud.design is not up to date. It is still the old content published from releases of https://github.com/owncloud/owncloud-design-system

Expected behavior

• design system docs can be built from within the web monorepo
• design system docs can be published to https://owncloud.design upon release of @ownclouders/design-system (whelp... that artifact doesn't exist yet, either).

Actual behavior

• design system docs cannot be built from within the web monorepo
• design system docs are not published anywhere

[JammingBen]

Some more technical info: building the docs stopped working after the upgrade to Vue 3. It's probably a good start to check if both vue-style-loader and vue-styleguidist are compatible with Vue 3. If I recall correctly they were not at the time (or we simply didn't care enough to check that properly).

[AlexAndBear]

It would be wonderful to have an actual version. I use the docs quite often. Big kudos if this works again.

[LukasHirt]

It's probably a good start to check if both vue-style-loader and vue-styleguidist are compatible with Vue 3.

Styleguidist seems to support Vue 3 but the vue-style-loader does not seem to do the same. It seems there is e.g. mini-css-extract-plugin that might be used instead.

[LukasHirt]

I did research whether styleguidist would still be the right fit and compared it to other solutions:

Styleguidist

Pros:

• Supports Vue 3.
• Requires several adjustments, but it should be possible to continue using it.
• Consistency with the current development approach.
• Minimal new knowledge required for the team.

Cons:

• Does not offer capabilities for developers to try out components in different states, etc. other than what is done in docs.
• If we want to keep using it as we do now, we need to stick with webpack.

Storybook

Pros:

• Provides a nice way for developers to try out different states, events, etc. of components in the browser.
• Provides similar way of documenting props and events like styleguidist does
• Docs-only pages can be created so we would not lose content.

Cons:

• Requires quite a big amount of changes to transition.
• More effort compared to Styleguidist.

Histoire

Pros:

• Similar to Storybook but easier to set up.
• Less effort required compared to Storybook.
• Built on top of Vite.

Cons:

• Still requires a significant amount of effort.

Full-Blown Design Docs Project

Pros:

• Offers a comprehensive documentation solution where we can handle whatever use case we would like.
• Potential for a playground for developers to experiment with components where they can even combine multiple components (we could use vue-live).
• We could build this on top of solutions like e.g. vitepress and thanks to that also have the docs static which would improve performance.

Cons:

• Requires the most effort.
• Requires creating wrappers for component examples.
• Time-consuming compared to the other solutions.

Recommendation

Vue Styleguidist appears to be the most suitable choice. It supports Vue 3, requires relatively fewer adjustments, and allows the team to stay consistent with the existing development approach. However, if the team is open to investing more effort for a more comprehensive solution with a playground, the full-blown design docs project (e.g. like Vuetify) could be considered, especially if the benefits align with long-term goals.

[dschmidt]

vue-styleguidist/vue-styleguidist#1363 (comment)

Could this be of any use?

I'm not keen on keeping webpack around to be honest, but if it's the most reasonable approach (idk), I would really like to see at least a few e2e Tests, so we can confidently accept renovatebot PRs to the ODS

[kulmann]

Thank you for the research @LukasHirt - I share your recommendation. We played around with and even started to switch to Storybook roughly 2 years ago in the design system repo. The efforts turned out to be too much, compared to the value it brings us. The current approach with vue-styleguidist already solves most of the things we wanted.

Since you came to the conclusion that making it work again should be possible, let's try that. It is the right choice with the current requirements.

[LukasHirt]

I'm not keen on keeping webpack around to be honest

This approach would basically tie into the "Full-Blown Design Docs Project". The automatic docs we have generated now (not only the props, slots, etc. but the whole site) is generated thanks to the styleguidist which supports only webpack.

If we go with vite (e.g. with vitepress as seen in the comment you posted), we would need to handle the docs ourselves. We can of course utilise the vue-live as mentioned and props and slots docs could still be extracted via the docgen api but the rest would be up to us to maintain (you can see this mentioned in comment above the one you posted).

[dschmidt]

I don't insist on getting rid of webpack...

The other part of my comment was more relevant imho: we need e2e tests for the docs

[LukasHirt]

Docs are now in state where they can be built and have E2E tests. If I should look also into publishing, I would probably need someone more familiar with the current release process to pair with or delegate the task.