upgrade codey development and documentation strategy

Status: Approved

Decision Date: 07/11/2022

Scope: General

Context

In the current setup, we have codey-documentation and codey-storybook to use and utilize components that are created within Codey. Both platforms have their own style flavor making it very difficult to create an environment where we can test components/composables in a nearly production like setting as teams will use them. It also makes it impossible to fully use codey-style as described by the docs.

The deployment strategy for this setup is also tightly coupled. For every version of the docs a storybook counterpart needs to exist. To get the full codey docs information we need to maintain and uphold 2 platforms.

Codey Documentation

The main purpose is to provide documentation on what codey has to offer to everyone within Xerius. This is, and not limited to:

• Component documentation and showcase
• Style & UX guidelines
• Variates of cookbook recipes to help and import DX
• npm package
  • Installation info
  • Changelog
  • Migration info

Overriding the base style in order to let all codey-components and styles work correctly clashes with the docs styles. This makes showcasing without isolation difficult.

Codey Storybook

This was to original place where all docs were kept. Since the codey-documentation, most of the written documentation has moved but still reference storybook for the showcases.

One issue with storybook is the syntax it requires to write stories. Because it has its roots in the react world, this is jsx. This requires you to know this in order to write the showcases and creates a larger barrier for maintenance. The most valuable feature of storybook, being able to change props on the fly and play with the components, is not used by our components or users. In order to allow this functionality you need to manually link the props to the inputs so storybook knows how to act upon them. This is not profitable as it not a requested feature by our end-users

Lastly, storybook was mainly used for developing or fixing bugs on components/styling. Because the environment mismatch against business applications this often made this task difficult and time consuming.

Decision

Storybook will be discontinued and all remaining docs will be moved to codey-documentation. This will be the main and only platform to hold all docs.

For development purposes, we decided to create a separate vue3 application to act as a playground for developing and potentially test new components and composables. As this is a vue app without any other layer on top of it, we can create an environment that matches production use cases. If required, we can deploy this allowing teams to view all possibles showcases.

Codey documentation will be upgrade to VuePress 2 which has vue 3 support. Even though it is still in beta at the time of writing, the risk is minimal as it is internal use only.

Within codey-components and codey-composables and example folder can be created under a component/composable for utilization within the playground. These examples will also serve as showcase for within the codey-documentation. This approach allows for keeping function related parts together instead of spreading them across multiple applications.

To limit maintenance, the playground routing table will be populated by scanning the codey-components and codey-composables for examples.

Consequences

• Remaining docs within storybook need to migrated
• The playground as application will need to maintained. This can also be an advantage in order to test migration steps when breaking changes would occur.
• Upgrading to a VuePress in beta can potentially require upgrade work when a final version is out.

Alternatives

• Histoire: Storybook alternative created purely for Vue
  • Not possible to use as we cannot change the layout around a story in order to wrap it in the Codey application shell (See Story 86236)