Guía para Documentar Apartados

Guía para documentar apartados

23/12/2025

Versión 0.1

Queda prohibido cualquier tipo de explotación y, en particular, la reproducción, distribución, comunicación pública y/o transformación, total o parcial, por cualquier medio, de este documento sin el previo consentimiento expreso y por escrito a overskull.

INDICE

1. Objetivo del Documento

2. Estructura del Documento
   2.1 Título del Apartado
   2.2 Objetivo del Apartado
   2.3 Roles y Permisos
   2.4 Reglas de Funcionamiento
   2.5 Flujos de Trabajo
   2.6 Ejemplo Documentado

3. Formato de Documentación
   3.1 Estilos de Texto
   3.2 Formato de Tablas
   3.3 Formato de Código / Script
   3.4 Notas
   3.5 Formato de Imágenes

4. Buenas Prácticas

5. Glosario de Términos (opcional)

6. Control de Versiones

1. Objetivo del Documento

Establecer un formato estándar y claro para documentar los apartados y procesos internos, incluyendo reglas de negocio, validaciones, restricciones por rol, flujos de trabajo y comportamientos especiales.

2. Estructura del Documento

2.1 Título del Apartado

• Debe contener el nombre exacto del módulo o apartado.

• Formato: Arial Bold, 18 pt, Color #000000, centrado.
  

2.2 Objetivo del Apartado

• Breve descripción de la funcionalidad general del apartado.
  

• Indicar qué operaciones permite realizar y a qué área está orientado.
  

2.3 Roles y Permisos

• Indicar qué funcionalidades están disponibles según el tipo de rol del usuario.
  

• Formato sugerido: tabla con columnas: "Rol", "Acción Permitida", "Restricción".

• Si no tuviera Roles y Permisos colocar el subtítulo y este mensaje “El apartado no  cuenta con Roles y Permisos”

2.4 Reglas de Funcionamiento

• Enumerar todas las reglas de validación o comportamiento del sistema. 

• Si no tuviera reglas de funcionamiento colocar el subtítulo y este mensaje “El apartado no cuenta con Reglas de Funcionamiento”

Ejemplo:

1. El rol Concesionario sólo puede solicitar productos de las categorías Tienda y Embalaje.
   

2. El rol Administrador de Agencia puede solicitar productos de cualquier categoría.
   

3. Al seleccionar una categoría, se asigna automáticamente el almacén correspondiente a la agencia.
   

4. Si se solicita un producto clasificado como "individual", se solicitará el nombre del empleado a quien se entregará.

2.5 Flujos de Trabajo

• Describir paso a paso el flujo de uso del apartado.
  

• Puede representarse con diagramas o numeración secuencial.

• Si no tuviera Flujos de Trabajo colocar el subtítulo y este mensaje “El apartado no cuenta con Flujos de Trabajo”
  

2.6 Ejemplo Documentado

• Incluir un caso de ejemplo completo con:
  

• Capturas de pantalla (ver sección de formato de imágenes).
  

• Datos de prueba.
  

• Resultado esperado.
  

3. Formato de Documentación

Imágenes:

• Tamaño sugerido: ancho 600px.
  

• Formato: JPG o PNG.
  

• Nombre de archivo: usar nomenclatura clara, ej. pantalla-solicitud-productos.png
  

• Deben tener pie de imagen descriptivo.
  

4. Buenas Prácticas

• Revisar ortografía y coherencia.
  

• Validar con usuario funcional antes de publicar.
  

• Versionar el documento si se hacen actualizaciones.
  

• Incluir fecha de última actualización y autor responsable.
  

5. Glosario de Términos (opcional)

• Incluir definiciones de términos técnicos o funcionales si son frecuentes en el documento.
  

6. Control de Versiones