manuales-factorpesca/references/calidad.md

Lista de comprobaciones pre-entrega

Ejecutar este checklist completo antes de declarar el manual terminado. Si falla cualquier punto, corregir y volver a generar el PDF.

1. Contenido

• El título de la portada coincide exactamente con el nombre de la aplicación.
• El índice lista todos los capítulos y secciones presentes en el cuerpo.
• Cada capítulo tiene al menos un objetivo explícito en un callout info.
• Cada proceso termina con un callout tip "Resultado final".
• La sección "Solución de problemas" existe y cubre al menos los tres errores más comunes.
• Los nombres de los botones, campos y menús son idénticos a los de la UI.
• Las acciones irreversibles están acompañadas de un callout warning o danger.

2. Capturas de pantalla

• Cada paso crítico tiene al menos una captura.
• Las capturas están en artifacts/ con nombres NN-slug.png.
• Ninguna captura contiene contraseñas, tokens, datos personales reales o identificadores confidenciales.
• Los banners de cookies, tooltips de onboarding y notificaciones están cerrados.
• Las anotaciones numeradas coinciden con el orden de los pasos en el texto.
• Las capturas se ven nítidas en la página impresa (probar zoom 100% en el lector de PDF).

3. Estilo y formato

• Todos los callouts tienen modificador correcto (info, warning, danger, tip, note).
• Ningún párrafo excede 4 líneas en pantalla.
• No hay cursivas decorativas; las negritas se usan solo para destacar UI ("Haga clic en Guardar").
• No hay colores fuera de la paleta autorizada (ver estilo.md).
• No hay tipografías distintas a Inter y JetBrains Mono.
• Los bloques de código usan pre code y no se parten a la mitad de página.

4. Numeración y referencias

• Los pasos siguen numeración global sin reiniciar.
• Las figuras se enumeran automáticamente y el caption coincide con el contenido de la imagen.
• Las referencias cruzadas (por ejemplo, "ver paso 4") son correctas.
• El índice generado automáticamente coincide con los encabezados reales.

5. Impresión y paginación

• Cada capítulo (h1) empieza en página nueva.
• Ningún heading queda al final de página sin contenido después.
• Ningún .step-block, .callout o figure se parte a la mitad.
• La cabecera muestra el nombre del capítulo actual.
• El pie muestra "Página X de Y" coherente (X nunca excede Y, Y es el total real).
• La portada y la página de aviso de propiedad no muestran cabecera ni pie.
• El aviso de propiedad menciona explícitamente a "FactorPesca S.A. de C.V." como titular del documento.
• La portada usa sangrado completo (el fondo navy llega al borde de la hoja).
• Las imágenes no pierden color ni contraste al imprimir (-webkit-print-color-adjust: exact).

6. PDF final

• El PDF se abre sin errores en al menos dos visores (Chromium y un lector externo como Preview o Acrobat).
• El tamaño del PDF es razonable (menos de 25 MB para manuales de hasta 60 páginas; reducir peso si supera).
• Los marcadores de navegación del PDF están generados para cada capítulo.
• El archivo de salida se llama manual-{aplicacion}-v{X.Y.Z}.pdf y se entrega en dist/.

7. Procedimiento de revisión

1. Generar el PDF.
2. Recorrer el manual página a página. Marcar cualquier desviación.
3. Corregir el HTML/CSS/JS fuente (nunca el PDF).
4. Volver a generar.
5. Repetir hasta que el checklist esté completo.
6. Marcar el manual como released en el changelog del proyecto.

8. Errores frecuentes

• PDF sin color de fondo: falta -webkit-print-color-adjust: exact. Revisar manual.css.
• TOC vacío: los headings no tienen data-toc o están dentro de contenedores excluidos. Revisar manual.js.
• Anotaciones mal posicionadas: las coordenadas no están en porcentaje. Revisar data-annotations.
• Pasos partiéndose a la mitad: falta break-inside: avoid o el contenido del paso es demasiado alto. Dividir el paso.
• Saltos de página inconsistentes: la cabecera/pie no están en @page. Revisar manual.css sección @page.

9. Limitaciones técnicas conocidas

• Números de página en el índice automático: el script manual.js no puede conocer el número de página final de cada sección en el momento de renderizar el PDF, porque Chromium solo expone esos números después de paginar. Por eso las entradas del TOC muestran — como número. Tres opciones para resolverlo:

  1. Aceptar la limitación: dejar el guion y añadir a mano los números tras la primera generación, editando templates/manual.html y usando data-toc-label con la numeración correcta.
  2. Hacer un build en dos pasadas: generar el PDF una vez, leer los números de página reales del PDF resultante y volver a renderizar con los números ya conocidos. Requiere un parser de PDF.
  3. Quitar los números del TOC: ocultar la columna derecha de cada fila del índice con CSS y dejar solo el nombre del capítulo/sección con sus líderes de puntos. Es la opción más limpia visualmente.

• Named pages en Chromium: el uso de @page cover y @page copyright está soportado pero requiere que la sección use exactamente la clase CSS correspondiente (cover, copyright-page, etc.) sin selectores anidados.