[Docs] Improve the documentation of the library

[aAmorim27]

Documentation RFC

• Start Date: 27-09-2022
• RFC PR: Feat/poc vitepress docs #56

Summary

• Create clear guidelines about writing a set of storybook stories when adding or improving a component in the library
• Use vitepress as our public documentation
• Use storybook/chromatic for UI reviews and visual regression testing

Motivation

Since the start of Puik we used a storybook deployed in chromatic as documentation & UI review tool but we never had defined a clear set of guidelines about how to write a good set of stories for a component.

By not having these guidelines we end up with too much stories for some components, the most recent example is the button component who has 9 color variants, each of the color variant has a story in storybook and the code difference between all the variants is just a different prop value.

During the development we also encountered a pain point, as our library provides two ways of implementing our components with Vue or HTML/CSS we must also provide code snippets for the two languages. But currently storybook doesn’t provide a way to switch between the two languages with the integrated code snippets. Sometimes we end up having big code snippets because the two languages coexist in the same snippet with HTML/CSS being obviously the bigger one. If someone is only looking for the vue documentation the snippets will be polluted with useless code for him.

This proposal aims to simplify our way to use storybook stories and improving our documentation readability for us and our users

Design Detail

Overview

• Each component must have a story (auto generated base story)
• Stories must document every useful case of your component
• The first story of each component must be a playground where storybook controls are usable
• If a component prop has multiple defined values make only one story and group them all
• Vitepress is the current potential solution for the public tech documentation
• Each component must have is own page in the vitepress docs (auto generated base page)
• The page will integrates the storybook previews and code snippets for each languages

Stories

On Puik each component must have a set of storybook story documenting all the differents states of the component.

The first story must be used as a playground story were storybook controls are enabled, it will help us to understand how to the component works and will provide a way to test edge cases when designers are doing the UI review. The others stories must have the controls set as disable.

If a prop on your component can have multiple defined values like for colors variants or sizes you do not need to create a story for each one of them instead you can group them inside one story.
As an example we can take the case of the button component, this component has 9 different variants, instead of having a primary, secondary... story we can create a Variants story which displays all the 9 variants.
By doing this we reduce the size of the story tree of the component which improves the navigation readability in the storybook and we also reduce our code in the story file.

Examples:

• Alert
  • New story (Code)
  • Old story (Code)
• Button
  • New story (Code)
  • Old story (Code)

Documentation

As of today our code documentation is on storybook and consists of one code snippet including two languages (Vue & HTML/CSS) in the same snippet for each story of a component which can be painful to maintain and to read for the user.

In order to improve our Dx (Developer Experience) on documentation i searched for a way to generate a documentation site by writting Markdown, i found VitePress which is a SSG using Vue 3 & Vite and i made a POC using some of the already existing documentation in Puik

Why using VitePress over another SSG ?

• It uses Vue 3
  • And our teams know how to use Vue
  • We can use the Puik components & custom vue components directly in the documentation
• Build times are pretty fast (thanks to Vite ⚡)
• Comes with a good default theme for technical documentation
• Has an easy to use integration with Algolia DocSearch which is free if the project becomes open source
• It’s the standard SSG for documentation on the Vue ecosystem (VueJS, Vite, Vitest docs already uses vitepress)

The documentation is splitted in two parts:

• Guide
  • Contains everything related to installing the library and how to use it
• Components
  • Contains all the components documentation
    • Preview of the component from storybook for each state
    • With an associated code snippet where the user can switch between the Vue snippet or the HTML/CSS snippet
    • Contains detailed tables about the components props, events & slots

Documentation POC:

• Code: Feat/poc vitepress docs #56
• Preview

Drawbacks

• Two sources to maintain
  • Storybook for listing states (preview only, UI review)
  • Vitepress for technical documentation (code snippets, install guide, lib usage)

Unresolved questions

• Can we improve our documentation flow by automatically generating documentation for components props/slots/events ? To investigate but It seems there is already some solutions like vuedoc/md or vue-docgen-cli
• Can the zeroheight used by the design team replace what we are doing with vitepress ?