samykabu/manual-de-usuario

Manual de Usuario

Mantén una fuente única en Markdown con respaldo de evidencia bajo User-Manual/. Publica tres ediciones: Usuario Final, Administrador/Operador y Referencia Técnica. El Markdown es el producto; el renderizado es un paso separado y reemplazable.

Elige el flujo de trabajo más pequeño

• Manual nuevo: entrevista al usuario, inspecciona el repositorio, propón un mapa de módulos, obtén aprobación, luego ejecuta scripts/init_manual.py con un archivo JSON de módulos aprobado.
• Manual existente: lee User-Manual/manual.yml, inspecciona el alcance solicitado y el diff de Git relevante, luego actualiza solo las páginas y activos afectados.
• Auditoría de cobertura: ejecuta scripts/audit_manual.py y explica cada error y advertencia.
• Construcción: ejecuta scripts/build_manual.py solo después de que la auditoría pase. Ensambla cada edición y luego la renderiza con renderer.kind en manual.yml: markdown (predeterminado), command o mkdocs.
• Frescura: scripts/manual_state.py record --feature <dir> después de una actualización; status sale con código 1 cuando las entradas o salidas del manual cambiaron desde el registro.

init_manual.py copia los scripts de construcción, auditoría y estado (y las hojas de estilo incluidas, en tools/theme/) a User-Manual/tools/ para CI. Después de actualizar este skill, actualiza esas copias desde su directorio scripts/. --no-tools omite las copias cuando CI ejecuta los scripts desde otra ubicación. Los flujos de trabajo de CI siguen el mapeo ci: en --ci-policy <file>, o en .specify/workflow.yml si existe.

Este skill no requiere .specify/, una especificación de características, ni ningún comando de Spec Kit. Enfoca el trabajo a partir de la solicitud del usuario, la evidencia del repositorio y los cambios del control de versiones.

Enruta solo lo necesario

Tarea	Lectura
Descubrimiento y entrevista	discovery.md
Estructura de página y sintaxis Markdown	content-model.md
Audiencia e idioma	audience-language.md
Cambios incrementales	incremental-update.md
Entidades, columnas, enumeraciones, diagramas ER	data-reference.md
Renderizadores, plantillas, marca, HTML, PDF, RTL	publishing.md
Documentación de API	api-docs.md
Notas de versión y guías de migración	release-docs.md
Capturas de pantalla de UI	ui-screenshots.md
Vistas previas y publicación de versiones	preview-publishing.md

Reglas no negociables

1. Exige inglés. El árabe es opcional por proyecto, pero las páginas, renderizadores, diagramas y PDFs deben soportar RTL desde la inicialización.
2. Usa inglés o árabe natural y sencillo. Escribe para la audiencia declarada; nunca reutilices una explicación técnica sin cambios para un usuario final.
3. Fundamenta las afirmaciones en la implementación, contratos, pruebas, comportamiento observado, esquemas o fuentes de infraestructura aprobadas. Marca lo desconocido y nunca inventes comportamiento.
4. Nunca incluyas secretos, credenciales, tokens, claves privadas, cadenas de conexión, registros de producción o datos personales no censurados. Usa ejemplos sintéticos deterministas.
5. Almacena el mapa de módulos aprobado y extensible en User-Manual/manual.yml. Agrega descubrimientos posteriores como propuesto hasta que se aprueben.
6. Mantén el Markdown canónico y escribe la sintaxis propia de GitHub, para que cada página se lea correctamente en GitHub; la construcción lo traduce para otros renderizadores. Genera otros formatos solo a través de la construcción.
7. Genera solo diagramas útiles, con el skill illustrate cuando esté instalado. Mantén las visiones generales del sistema separadas del detalle legible a nivel de módulo: una visión general ER del sistema más diagramas ER de módulos más pequeños. Documenta cada entidad, columna, tipo de datos, relación, restricción y enumeración con evidencia.
8. Preserva el contenido escrito a mano fuera de los marcadores propietarios y haz que las reejecuciones converjan.
9. Enlaza una página solo a páginas que su audiencia reciba. La construcción rechaza enlaces entre audiencias y activos faltantes, y prepara solo los activos a los que llegan las páginas de una edición, para que una audiencia nunca envíe capturas de pantalla o ejemplos de otra.

Ejemplo real

Para "Crear un manual para nuestra plataforma de reservas", identifica los módulos de reserva, cliente, pago y operaciones a partir de rutas, navegación, APIs, pruebas y archivos de esquema. Pide al usuario que apruebe ese mapa de módulos. Luego crea tutoriales adaptados a la audiencia, capturas de pantalla seguras, referencias de API y datos, contenido en inglés y contenido opcional en árabe bajo User-Manual/, y renderízalo de la manera que el proyecto elija: Markdown en GitHub, la plantilla de Word del equipo a través de Pandoc, o un sitio MkDocs con PDFs.