24 de abril de 2026
Arquitectura de contenido
Criterios para mantener la wiki de Ballista clara, navegable y útil para usuarios, soporte, ventas consultivas y búsqueda pública.
Esta guía define cómo mantener la wiki de Ballista sin que se vuelva una colección de páginas sueltas. El objetivo no es escribir para robots ni llenar textos con palabras clave; el objetivo es que una persona entienda qué problema resuelve cada guía, qué flujo toca y qué acción puede tomar después.
Una buena documentación sirve para varias cosas al mismo tiempo: incorporación, soporte, ventas consultivas, búsqueda y alineamiento interno. Para lograrlo, cada página debe tener una intención clara y conectarse con el resto del sistema.
Principios Editoriales
| Principio | Qué significa |
|---|---|
| Escribir desde el flujo | Empezar por la acción del negocio, no por la implementación. |
| Usar rutas reales | Nombrar pantallas y botones tal como aparecen en Ballista. |
| Separar niveles | Manual para aprender, guías profundas para operar, ayuda contextual para dudas puntuales. |
| Evitar relleno búsqueda | Las palabras clave deben aparecer porque son naturales, no porque se repiten. |
| Cerrar con acción | Cada guía debe dejar claro qué revisar, qué corregir o dónde pedir ayuda. |
Arquitectura Recomendada
| Nivel | Ruta | Función |
|---|---|---|
| Entrada | /learn | Presenta el área educativa. |
| Hub | /learn/systems | Ordena la wiki por operación, gobierno y plataforma. |
| Manual | /learn/systems/manual | Enseña Ballista como recorrido de uso. |
| Áreas principales | Operación, Gobierno, Plataforma | Agrupan flujos relacionados. |
| Guías profundas | Pedidos, Tareas, Reportes, Facturación, Inventario | Explican pantallas críticas con detalle operativo. |
| Ayuda por pantalla | /learn/ballista/help | Resuelve dudas mientras se usa la app. |
El manual funciona como ruta de aprendizaje. Las guías profundas funcionan como referencia. La ayuda por pantalla funciona como soporte rápido.
Intenciones por Página
| Intención | Página objetivo |
|---|---|
| Aprender Ballista de principio a fin | Manual guiado |
| Crear y dar seguimiento a pedidos | Pedidos y ventas |
| Coordinar trabajo pendiente | Tareas |
| Controlar inventario disponible y producción | Inventario y producción |
| Leer indicadores y decidir | Reportes y decisiones |
| Emitir y auditar comprobantes | Facturación y control |
| Pedir ayuda con contexto | Cambios seguros |
| Aprender con tour guiado | Adopción de uso |
Si una página intenta cubrir demasiadas intenciones, conviene dividirla. Si dos páginas responden la misma pregunta, conviene fusionarlas o marcar claramente cuál es la principal.
Estructura de una Guía Profunda
| Sección | Propósito |
|---|---|
| Introducción | Explica el valor del flujo en lenguaje de negocio. |
| Rutas | Aclara dónde ocurre el flujo. |
| Antes de usar | Enumera datos, permisos o configuraciones necesarias. |
| Estructura visual | Explica qué ve la persona en la pantalla. |
| Acciones principales | Describe botones, formularios y estados. |
| Flujo recomendado | Da una secuencia realista de uso. |
| Validaciones y errores | Explica bloqueos frecuentes y cómo corregirlos. |
| Conexiones | Enlaza módulos relacionados. |
| Para soporte | Dice qué datos incluir en un ticket. |
| Resumen | Resume la idea operativa principal. |
No todas las páginas necesitan la misma longitud. Una guía de Pedidos o Reportes puede ser larga; una guía de soporte puede ser más breve. Lo importante es que el lector no termine preguntándose “¿y ahora qué hago?”.
Enlaces Internos
| Desde | Debe conectar con |
|---|---|
| Manual | Pedidos, Tareas, Inventario, Facturación, Reportes y Plataforma. |
| Pedidos | Inventario, Tareas, Facturación y Reportes. |
| Tareas | Pedidos, Reportes y soporte. |
| Inventario | Pedidos, Reportes y Cambios seguros. |
| Facturación | Pedidos, Reportes, historial de facturación y Configuración. |
| Reportes | Pedidos, Tareas, Inventario y Facturación. |
| Adopción de uso | Manual, Pedidos, Tareas y Reportes. |
| Cambios seguros | Facturación, Pedidos, Reportes y Adopción de uso. |
La regla práctica: si una guía menciona una acción que vive en otro módulo, debe enlazarla.
Tono Recomendado
La wiki debe sonar como documentación de producto escrita por alguien que conoce la operación:
| Evitar | Preferir |
|---|---|
| “Esta página es una solución integral robusta…” | “Esta pantalla ayuda a revisar pedidos pendientes antes de prometer entrega.” |
| “En simple…” repetido en cada artículo | Explicar directamente con un ejemplo concreto. |
| “Debe/debería” en exceso | Usar criterios claros: “Conviene revisar…”, “Antes de emitir, confirma…”. |
| Palabras clave visibles | Títulos, enlaces y ejemplos naturales. |
| Detalles internos sin contexto | Detalle técnico solo cuando ayuda a soporte o evita errores. |
Checklist Antes de Publicar
| Revisión | Pregunta |
|---|---|
| Promesa clara | ¿El título dice qué aprenderá la persona? |
| Valor operativo | ¿El primer párrafo habla del trabajo real? |
| Rutas reales | ¿Las URLs y botones existen en la app? |
| Profundidad suficiente | ¿Explica flujo, errores y soporte, no solo la pantalla? |
| Enlaces | ¿Conecta con módulos relacionados? |
| Lenguaje | ¿Suena humano, específico y sobrio? |
| Soporte | ¿Incluye qué datos reportar si algo falla? |
| Actualización | ¿La fecha y el contenido siguen vigentes? |
Cómo se Conecta
Esta guía sostiene la calidad editorial del Manual guiado, de Adopción de uso y de Cambios seguros. Si el contenido cambia mucho, conviene registrar la decisión en la bitácora operativa del proyecto para que el equipo entienda por qué cambió la estructura.
Resumen
La wiki debe enseñar Ballista por recorridos reales: qué hago, dónde lo hago, qué datos necesito, qué puede fallar y cómo pido ayuda. La búsqueda pública mejora cuando el contenido es claro; no necesita sonar forzado.