# Guía para Documentar Apartados

![](https://shalom-documentation.shalomcontrol.com/uploads/images/gallery/2025-12/embedded-image-qdbolhp1.png)

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

<div align="left" dir="ltr" id="bkmrk-elemento-fuente-tama"><table><colgroup><col width="127"></col><col width="80"></col><col width="75"></col><col width="82"></col><col width="268"></col></colgroup><tbody><tr><td>Elemento

</td><td>Fuente

</td><td>Tamaño

</td><td>Color

</td><td>Observaciones

</td></tr><tr><td>Título

</td><td>Arial Bold

</td><td>18 pt

</td><td>\#333333

</td><td>Centrado

</td></tr><tr><td>Subtítulos

</td><td>Arial Bold

</td><td>14 pt

</td><td>\#333333

</td><td>Alineado a la izquierda

</td></tr><tr><td>Texto normal

</td><td>Arial

</td><td>12 pt

</td><td>\#000000

</td><td>Interlineado 1.5

</td></tr><tr><td>Tablas

</td><td>Arial

</td><td>11 pt

</td><td>\#000000

</td><td>Bordes finos

</td></tr><tr><td>Código/Script

</td><td>Consolas

</td><td>10 pt

</td><td>\#333333

</td><td>Fondo gris claro opcional

</td></tr><tr><td>Nota

</td><td>Arial Italic

</td><td>11 pt

</td><td>\#0070C0

</td><td>Usar solo para mensajes aclaratorios o tips

</td></tr></tbody></table>

</div>#### 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

<div align="left" dir="ltr" id="bkmrk-versi%C3%B3n-fecha-autor-"><table><tbody><tr><td>Versión

</td><td>Fecha

</td><td>Autor

</td><td>Comentario

</td></tr><tr><td>1.0

</td><td>\[Fecha\]

</td><td>\[Nombre\]

</td><td>Documento base de documentación

</td></tr></tbody></table>

</div><div drawio-diagram="2456"><img src="https://shalom-documentation.shalomcontrol.com/uploads/images/drawio/2025-12/drawing-14-1767114839.png" alt=""/></div>