manuales-factorpesca/references/estructura.md

Estructura del documento

Anatomía obligatoria de cualquier manual generado por esta skill. Omite o añade secciones solo si el usuario lo pide explícitamente.

Visión general

1. Portada
2. Índice
3. Resumen ejecutivo
4. Requisitos previos
5. Capítulo 1
6. Capítulo 2
...
N. Solución de problemas
N+1. Glosario (opcional)
N+2. Aviso de propiedad y confidencialidad (obligatoria)

1. Portada

Elementos obligatorios:

• Logo de FactorPesca (placeholder hasta que se sustituya por el definitivo).
• Eyebrow en accent color (por defecto «Manual de usuario»).
• Título del manual: "Manual de [Aplicación]".
• Subtítulo descriptivo de una línea.

La portada es deliberadamente minimalista: solo logo, eyebrow, título y subtítulo. Sin versión, fecha de emisión, autor ni metadatos.

Plantilla HTML: la primera página dentro de templates/manual.html con clase cover. Forzar break-after: page en @media print.

2. Índice

• Generado automáticamente por manual.js a partir de los h1, h2, h3 del documento.
• Numeración con líderes de puntos (CSS leader).
• Mostrar solo h1 y h2 por defecto. Si un capítulo tiene muchas sub-secciones, incluir h3 discretamente con sangrado.
• Numeración: capítulos en romanos (I, II, III), secciones en arábigos (1.1, 1.2).

3. Resumen ejecutivo

• Una página con tres bloques:
  1. Objetivo: para qué sirve el manual y qué aprenderá el lector.
  2. Audiencia: a quién va dirigido (operadores, supervisores, administradores, etc.).
  3. Alcance: qué procesos cubre y qué procesos quedan fuera.

Si el manual es muy largo (>40 páginas), dividir el resumen en "objetivo" y "cómo leer este manual".

4. Requisitos previos

Lista de todo lo que el lector necesita antes de empezar:

• Software: navegador, sistema operativo, plugins.
• Cuenta: tipo de usuario y permisos necesarios.
• Datos: archivos, credenciales o recursos de entrada.
• Conocimientos: formación previa recomendada.

Estructura como .checklist o .data-table con dos columnas ("Requisito", "Detalle").

5. Capítulos (núcleo del manual)

Un capítulo por proceso de usuario. Estructura interna:

1. Encabezado del capítulo (<h1 data-chapter>)
2. Objetivo del capítulo (caja .callout-info con título "Objetivo").
3. Pasos (cada uno un .step-block).
4. Resultado del proceso (caja .callout-tip con título "Resultado final").
5. Errores comunes (caja .callout-warning con título "Errores comunes"), si aplica.

Reglas:

• Un capítulo describe un proceso completo. Si el proceso es muy largo, dividirlo en varios capítulos, pero numerarlos con un prefijo común (4.1, 4.2, 4.3).
• El primer paso de cada capítulo debe incluir una captura del estado inicial (pantalla previa).
• El último paso debe mostrar el estado final con un callout tip "Resultado final".
• Evitar capítulo con más de 12 pasos. Si los hay, dividir.

6. Solución de problemas

Apartado obligatorio. Estructura:

<section id="troubleshooting">
  <h1>Solución de problemas</h1>
  <p>Si encuentra algún error, busque el síntoma en esta sección antes de contactar al soporte.</p>

  <article class="trouble">
    <h3 class="trouble-symptom">No puedo iniciar sesión</h3>
    <p><strong>Causa probable:</strong> la cuenta está bloqueada tras tres intentos fallidos.</p>
    <p><strong>Solución:</strong> espere 15 minutos o solicite el desbloqueo al administrador.</p>
  </article>
  ...
</section>

Cada problema: síntoma, causa, solución. Como máximo cinco problemas por bloque; si hay más, agrupar por categoría con <h2>.

7. Glosario (opcional)

Tabla de dos columnas: término, definición. Incluir solo si el manual usa jerga técnica o nombres propios.

8. Aviso de propiedad y confidencialidad (obligatoria)

Última página del manual. Su propósito es reforzar visualmente que el documento es propiedad privada de FactorPesca S.A. de C.V. y establecer las restricciones de uso, reproducción y divulgación.

Elementos obligatorios:

• Marca © grande en la parte superior.
• Razón social completa: FactorPesca S.A. de C.V.
• Subtítulo "Todos los derechos reservados."
• Título centrado: "Aviso de propiedad y confidencialidad".
• Cinco párrafos numerados en lenguaje formal que cubran:
  1. Propiedad intelectual sobre todos los elementos del documento.
  2. Prohibición de reproducción, distribución y transformación sin autorización escrita.
  3. Carácter privado y confidencial de la información, y obligación de devolución o destrucción al término de la relación.
  4. Reconocimiento de marcas registradas de terceros.
  5. Ausencia de garantía y limitación de responsabilidad.
• Caja de contacto (callout primario) con el correo del área legal: legal@factorpesca.com.
• Pie pequeño con la atribución de la skill y la tipografía usada.

Sin cabecera ni pie de página (clase no-chrome y named page copyright). El borde superior de 6pt en color primary marca la transición desde el contenido del manual hacia el cierre legal.

Numeración y jerarquía

• Capítulos: I, II, III...
• Secciones: 1.1, 1.2, 2.1...
• Sub-secciones: 1.1.1, 1.1.2...
• Pasos: numeración global con círculo de accent (1, 2, 3...). No reiniciar en cada capítulo.
• Figuras: Figura 1., Figura 2.... (auto-numeradas por manual.js).
• Tablas: Tabla 1., Tabla 2.... (auto-numeradas por manual.js).

Saltos de página

• h1 siempre en página nueva (break-before: page).
• h2 puede fluir, pero nunca quedar al final de la página (break-after: avoid en el heading + break-before: avoid en el primer párrafo).
• Ningún .step-block puede partirse a la mitad (break-inside: avoid).
• Una figura o tabla debe vivir entera en la misma página, salvo que sea muy alta: en ese caso, el caption se imprime en ambas páginas.

Encabezados y pies

Configurados en manual.css con @page Paged Media. Cada página muestra:

• Cabecera: nombre del capítulo actual (eyebrow small caps).
• Pie izquierda: "FactorPesca · Manual de usuario de [Aplicación]".
• Pie derecha: "Página X de Y".

Las páginas marcadas con .no-chrome (portada, aviso de propiedad) ocultan cabecera y pie.