Documentación de aplicaciones

Plantillas

Este tipo de documentación sobre apps ayuda a los usuarios a comprender las aplicaciones VTEX, incluyendo la instalación y la configuración.

Para agregar documentación a una aplicación, debes usar Docs Builder. La documentación se escribe en archivos Markdown dentro del repositorio de la aplicación. Al usar Docs Builder, la documentación pasa a estar disponible públicamente en el VTEX Developer Portal.

En esta guía conocerás la plantilla disponible, las pautas generales y ejemplos de artículos de onboarding.

Esta guía forma parte de las directrices de la App Store y es uno de los requisitos para enviar una app al proceso de homologación y publicarla en la App Store.

Redactar documentación de aplicaciones

Audiencia

Descripción: Identifica a tus lectores.

✅ Correcto	❌ Incorrecto
Diferencia entre desarrolladores y usuarios de negocio.	Suponer que hay una audiencia única.

Objetivos de aprendizaje

Descripción: Define la conclusión principal que debe obtener el usuario.

✅ Correcto	❌ Incorrecto
Indica claramente qué deben aprender los usuarios.	Dejar los objetivos de aprendizaje ambiguos.

Título

Descripción: Utiliza un título claro y conciso.

✅ Correcto	❌ Incorrecto
Utiliza el nombre de la aplicación y un verbo que describa el objetivo de aprendizaje. Escribe con mayúscula la primera letra de cada palabra.	Incluir signos de puntuación, números de versión o la palabra `App`.

Introducción

Descripción: Presenta brevemente la aplicación y sus beneficios.

✅ Correcto	❌ Incorrecto
Resume el propósito de la aplicación y los beneficios para el usuario. Incluye una imagen y callouts para avisos importantes.	Centrarse exclusivamente en los detalles técnicos.

Antes de comenzar (opcional)

Descripción: Enumera los requisitos previos a la instalación.

✅ Correcto	❌ Incorrecto
Utiliza viñetas o listas de verificación claras. Utiliza callouts si corresponde.	Redactar párrafos extensos explicando los requisitos previos.

Instalación

Descripción: Proporciona una guía paso a paso con fragmentos de código (si corresponde).

✅ Correcto	❌ Incorrecto
Proporciona pasos claros y concisos. Mejora la claridad con fragmentos de código.	Omitir pasos o no incluir instrucciones específicas.

Configuración

Descripción: Guía a los usuarios a través de la configuración de la aplicación.

✅ Correcto	❌ Incorrecto
Enumera todos los ajustes esenciales con pasos detallados, tal como se define en settingsSchema.	Omitir detalles de configuración.

Cómo funciona

Descripción: (Opcional) Detalla las funciones de la aplicación y proporciona los pasos para usarla.

✅ Correcto	❌ Incorrecto
Utiliza listas numeradas para cada operación, con pasos claros y concisos. Utiliza imágenes para ilustrar la interfaz de usuario.	Omitir pasos o carecer de instrucciones específicas.

Personalización

Descripción: (Opcional) Proporciona los pasos para personalizar la aplicación.

✅ Correcto	❌ Incorrecto
Incluye CSS handles y una tabla relacionada, si corresponde. Consulta la documentación externa para obtener información sobre la personalización de CSS.	Ignorar las opciones de personalización.

Colaboradores

Descripción: (Opcional) Reconoce la contribución de los colaboradores.

✅ Correcto	❌ Incorrecto
Sigue el contenido estipulado en All-Contributors specification.	Omitir el reconocimiento de los colaboradores.

Callouts

Descripción: (Opcional) Reconoce la contribución de los colaboradores.

✅ Correcto	❌ Incorrecto
Resalta la información mediante callouts.	Utiliza los tipos de callout proporcionados (Information, Warning, Danger) con los mensajes apropiados. Utilizar texto genérico para resaltar la información.

Plantilla de documentación de aplicaciones

Plantilla de documentación de aplicaciones


# `{Inserta el nombre de la aplicación}`
`{insertar nombre de la aplicación}` `{propósito de la aplicación empezando con un verbo}` para poder `{tarea a realizar}`.
![insertar-una-vista-previa-de-imagen](/)
## Antes de comenzar
Necesitas tener `{insertar lo que el usuario necesita tener: una cuenta en otra plataforma, CLI, conocimiento sobre otra aplicación, etc.}`.
Si no tienes `{insertar lo que el usuario necesita tener y cómo obtenerlo}`.
## Instalación
1. [Instala](https://developers.vtex.com/vtex-developer-docs/docs/vtex-io-documentation-installing-an-app) la aplicación `{insert app name}` en la cuenta VTEX deseada ejecutando `vtex install {appVendor}.{appName}` en tu terminal.
2. (Opcional, para aplicaciones frontend) Abre el directorio de la aplicación Store Theme en tu editor de código.
3. (Opcional, para aplicaciones frontend) Abre el archivo `manifest.json` de la aplicación y agrega la aplicación `{insertar nombre de la aplicación}` en el campo `peerDependencies`.
      "peerDependencies": {
          "vtex.{appName}": "{appVersion}"
      }
      
4. (Opcional, para aplicaciones frontend) Declara la aplicación `{insertar nombre de la aplicación}` en la plantilla deseada. Por ejemplo:
      "store.home": {
          "blocks": [
      +     "{app-name}",
          ]
      },
*![insertar-una-imagen-de-vista-previa](/)*
## Configuración
Una vez instalada la aplicación, puedes `{describir la configuración de la aplicación en el Admin VTEX como se define en settingsSchema[https://developers.vtex.com/docs/guides/vtex-io-documentation-manifest#settingsschema], por ejemplo}`.
1. `Primer paso`.
2. `Segundo paso`.
3. `Tercer paso`.
## Personalización (Opcional, para aplicaciones de frontend)
Para aplicar personalizaciones CSS a este y otros bloques, sigue las instrucciones de [Using CSS Handles for store customization](https://developers.vtex.com/vtex-developer-docs/docs/vtex-io-documentation-using-css-handles-for-store-customization).
| CSS Handles |
| ------------------ |
| csshandlesName |
| csshandlesName |
| csshandlesName |
## Cómo funciona la aplicación (opcional)
Utiliza esta sección para [aplicaciones del Admin](https://learn.vtex.com/docs/course-admin-lang-en) cuando la aplicación requiera interacción del usuario más allá de la configuración de administrador.
`{Detalla qué se puede hacer con la aplicación y proporciona los pasos para realizar cada operación.}`
## Contribuidores
Agradecemos la labor de estas maravillosas personas:
- `{insertar el nombre de usuario de GitHub}`
Este proyecto sigue la especificación de [all-contributors](https://github.com/all-contributors/all-contributors). Se agradecen las contribuciones de cualquier tipo.

Redactar documentación de aplicaciones

Plantilla de documentación de aplicaciones

Ejemplos de artículos de documentación de aplicaciones