Contribuir a esta documentación

Esta documentación crece junto al producto. Cada cambio que afecta a clientes, integradores o operadores se documenta aquí en el mismo PR que introduce el cambio. Sin excepción.

Regla operativa

Cada PR que toca contrato publico (endpoint API, función del SDK, setting visible del panel, comportamiento user-facing) debe incluir el update correspondiente de packages/docs/content/ en el mismo PR. Es parte del Definition of Done.

Esta pagina explica como hacerlo bien y que herramientas usar.

Cómo se ve

Antes de entrar en reglas, aquí tienes ejemplos vivos de los componentes que esta misma sección documenta. Las capturas son del propio sitio docs.mibizum.io en producción.

Home de docs.mibizum.io - estetica developer-docs en modo oscuro

Una pagina de guía: sidebar jerarquico, contenido central, tabla de contenidos a la derecha

1. Landing

El home presenta el producto en 3 ejes. Hero + 6 features + quickstart inline.

Paso 1 de 4

Cuándo hay que actualizar la doc

Tipo de cambio	Doc a actualizar
Endpoint REST nuevo, modificado o eliminado	/api/<recurso> + nav
Función nueva o cambio de signatura en SDK	/sdk/<area>
Setting nuevo del panel	/quickstart/conceptos + pagina del feature
Concepto nuevo del producto	/quickstart/conceptos + /resources/glossary
Código de error nuevo o renombrado	/api/errors + /resources/errors si afecta UX
Cambio breaking del API	/resources/changelog con sección Breaking
Lección aprendida en hotfix relevante a merchants	/guides/<slug> (manual o vía script de sync)
Refactor interno sin cambio de contrato	No requiere doc
Bug fix que devuelve el comportamiento previamente documentado	No requiere doc (si el bug estaba documentado, quitar)

En duda, documenta. Es más barato escribir un parrafo de más que dejar deuda silenciosa.

Herramientas disponibles

<Screenshot>

Componente Vue para insertar capturas con sombra, borde redondeado y zoom al hacer click. Ya esta registrado globalmente en el tema, no hace falta import.

<Screenshot
  src="/screenshots/panel-aprendizaje.png"
  alt="Panel de Aprende del cliente con sugerencias IA"
  caption="La pestaña Aprende del cliente muestra las sugerencias del aprendizaje IA pendientes de revision."
/>

Las imagenes viven en packages/docs/content/public/screenshots/. Se referencian con path absoluto desde la raiz del sitio (/screenshots/...).

<TourCarousel>

Componente Vue para secuencias multi-paso con prev/next y contador. Pensado para feature-shows y onboardings. Navegación por teclado (flechas).

<TourCarousel
  :steps="[
    {
      src:   '/screenshots/onboarding-1.png',
      alt:   'Crea tu tenant',
      title: '1. Crea tu tenant',
      body:  'Elige un slug que identifique tu instancia. No se puede cambiar despues.'
    },
    {
      src:   '/screenshots/onboarding-2.png',
      alt:   'Carga tu primer catalogo',
      title: '2. Carga tu primer catalogo',
      body:  'Sube los items via API REST o instala el adapter de tu plataforma.'
    },
    {
      src:   '/screenshots/onboarding-3.png',
      alt:   'Configura el widget',
      title: '3. Configura el widget',
      body:  'Pega el script tag en tu tienda y el buscador se autoinstala.'
    }
  ]"
/>

¿Carousel o secuencia estática?

• Carousel (<TourCarousel>): mejor para mostrar features completas en pocas pantallas. Pulido. Bueno para landings.
• Secuencia estática (varios <Screenshot> en línea con texto entre cada uno): mejor para guías técnicas paso-a-paso. Más legible para imprimir o ctrl+F. Recomendado por defecto en /guides/ y /quickstart/.

Ejemplo de secuencia estática:

### 1. Crea tu tenant

<Screenshot src="/screenshots/paso-1.png" alt="..." caption="..." />

Texto que explica el paso 1.

### 2. Carga tu catalogo

<Screenshot src="/screenshots/paso-2.png" alt="..." caption="..." />

Texto que explica el paso 2.

Containers de callout

VitePress soporta nativamente:

::: tip Titulo opcional
Para informacion adicional util.
:::

::: warning
Para algo que el lector tiene que tener en cuenta.
:::

::: danger
Para errores graves o anti-patrones criticos.
:::

::: info
Para datos neutros.
:::

Capturas: de donde sacarlas

Las capturas del panel admin que aparecen en la doc vienen del tenant demo publico (mibizum.io/login con la cuenta demo, ver /quickstart para credenciales). El tenant demo tiene un catalogo ficticio neutro y datos generados para que las capturas sean fieles al producto real sin exponer información de comercios reales.

No uses capturas con datos reales de comercios

Si una captura muestra emails, queries con nombres de cliente, IPs, ordenes o cualquier dato PII de un merchant real, el cambio se rechaza en review. Usa siempre el tenant demo o ofusca con script.

Estilo

• Español en todo el copy (lengua de trabajo del producto).
• Hyphen-minus ASCII - como guion, nunca — ni –. Si una aposición envolvente lo pide, usa (parentesis).
• No nombres tecnologias de terceros en copy publico: motor de búsqueda en lugar de su nombre comercial; aprendizaje IA / Smart Mibizum en lugar del modelo concreto.
• Concisión sobre exhaustividad: una pagina debe poder leerse de un tiron. Si crece mucho, divide en sub-paginas.
• Ejemplos reales con números: "en una tienda de N items, X queries devolvian 0" es 10 veces más útil que "puede haber muchas queries sin resultados".
• Anti-patrones documentados: tras la regla, añade un bloque "Como NO hacerlo" con el caso real que se intento y por que falla.