Escribiendo Documentación

Escribir documentación usando markdown es simple y efectivo, pero no siempre es fácil ver el resultado de lo que escribes mientras lo haces. Sensedia Docs proporciona una extensión para VSCode que te permite visualizar tus archivos markdown a medida que los escribes.

📋 Tabla de Contenidos

1. Introducción
2. Uso de la Extensión de VSCode
3. Estructura del documento
4. Jerarquía del documento
5. Conclusión
6. Preguntas frecuentes

Introducción

Escribir documentación es una parte crucial del proceso de desarrollo. Ayuda a los usuarios a entender tu producto y sus características, y también puede servir como referencia para desarrollos futuros. En esta sección, discutiremos algunas buenas prácticas para escribir documentación efectiva usando Sensedia Docs.

Uso de la Extensión de VSCode

Sensedia Docs proporciona una extensión para VSCode que te permite visualizar tus archivos markdown mientras los escribes. Esta extensión ofrece una vista previa en vivo de tus archivos markdown, para que puedas ver cómo se verá tu documentación sin tener que publicarla primero.

Pasos para usar la Extensión de VSCode

Estructura del Documento

Al escribir documentación, es importante seguir una estructura consistente para evitar errores al renderizar el markdown. Aquí tienes una estructura básica que puedes seguir:

Explicación de la Estructura

• Front Matter: La sección en la parte superior del documento encerrada entre ---
  • title: El título de tu documento.
  • description: Una breve descripción del documento.
  • keywords: Palabras clave relacionadas con el documento para optimización de búsqueda.
  • parent: El documento o sección padre al que pertenece este documento.
  • icon: Ruta a un ícono que representa el documento. Requerido para categorías de producto o documento principal de productos.
  • order: El orden en que este documento debe aparecer en la navegación.
  • swagger: Opcional, se usa para incluir documentación Swagger.
• Contenido: El cuerpo principal de tu documento, escrito en sintaxis markdown.

Documento de Ejemplo

Jerarquía del Documento

Sensedia Docs te permite crear una jerarquía de documentos usando el campo parent en el front matter. Esto ayuda a organizar tu documentación en secciones y subsecciones, facilitando la navegación para los usuarios.

Ejemplo de Jerarquía de Documentos

En el contexto de Sensedia Docs, el último documento en la jerarquía es el sensedia-docs, que es el documento principal que contiene todos los demás documentos. Sirve como la raíz de tu estructura de documentación. No olvides establecer el campo parent como sensedia-docs en tu documento principal.

Beneficios de la Jerarquía de Documentos

• Organización: Ayuda a mantener juntos los documentos relacionados.
• Navegación: Los usuarios pueden navegar fácilmente por secciones y subsecciones.
• Claridad: Proporciona una estructura clara para tu documentación.

Conclusión

La extensión de Sensedia Docs para VSCode agiliza el proceso de documentación al proporcionar retroalimentación instantánea y vistas previas en vivo, facilitando la creación de contenido claro y visualmente atractivo. Aprovechar los componentes markdown de Sensedia Docs mejora aún más la experiencia del usuario, permitiéndote construir documentación interactiva y bien estructurada que sea informativa y atractiva.

Preguntas frecuentes