Improve documentation code preview & versioning

[lucasaarcoverde]

Problem

There are two main issues with our current code playground:

Code edition doesn’t work well
We can’t edit the code because the keyboard pointer is not right, as you can see in the gif below.

Versioning
Every time we have a breaking change the documentation referent to the change breaks and we need to remove the code preview or fix the breaking change in the documentation, and this is hard to maintain.

Why this matters?

The code preview and the playground are one of the most essential parts of the documentation, it’s the place that the developers can use as a reference in their applications. It isn't good the way it is right now.

Proposal

My proposal is to change the code playground with Sandpack, which is already being used in the Template code section.

I did a POC and it seems relatively easy to change from the current one. In this POC you can check the version 0.131.x and 0.135.x on the Alert component. You can check the changes in the code here

Pros

• Versioning works
• Each preview can be opened on Codesandbox by default
• Sandpack is composable and very flexible
• We can implement it incrementally

Cons

• The local change isn’t reflected in the code preview anymore, since Sandpack takes the library from NPM. (This is ok because we always release a dev version and we can point the Sandpack preview on the next to those versions)
• This will require a manual change to the code. (We can do it in baby steps)
• Since the code runs on code sandbox and not locally, the preview takes a longer time to load

What is the change?

Before

// component.mdx

``jsx live

<Component />
``

``jsx live

function Example() {
  return <Component />
}
``

After

// component.mdx
import version from '../version' //This is the admin-ui version which can be versioned with the docs

<Sandpack version={version}>

``jsx App.js // We can change it to tsx

import { Component } from '@vtex/admin-ui'

export default function App() {
  return <Component />
}
``

</Sandpack>

What's next

Get reviews and comments on this RFC to check if is worth it to follow with the implementation of this solution

[davicostalf]

Comentários no CSAT de Engenharia em 2023 H1:

A documentação peca bastante, muitas vezes prefiro ver a tipagem dos componentes para entender como o componente funciona, falta insumo para o propósito de certos componentes também, isso sem contar documentação defasada e o código dos componentes que é impossivel de selecionar e copiar.
Um bug reportado a muito tempo que nao se resolve.

Bom exceto pelo editor de texto/preview que temos na doc. Quando tentamos selecionar algo ali, tem algum flick entre a posição do mouse e da linha que está sendo de fato, selecionada

às vezes falta alguns exemplos de caso de uso, e sempre tenho problema ao copiar o código dos exemplos

A documentação é muito boa! Só acontece com alguma frequência de alguma doc estar quebrada (sem abrir) ou desatualizada. Mas em geral é tudo muito bem explicado, com um claro cuidado por parte do time.

[davicostalf]

@lucasaarcoverde Is this discussion still relevant?