# Reglas para Estructurar Listas en la Documentación Técnica
Las listas logran un equilibrio efectivo entre la prosa lineal y las tablas para organizar la información. Usa listas numeradas para acciones secuenciales donde el orden importa: pasos de instalación, algoritmos. Usa listas sin orden para colecciones de elementos sin una secuencia estricta: parámetros, componentes.
Mantén las listas a una longitud razonable. Las listas que abarcan cientos de líneas son difíciles de escanear: divídelas en subsecciones o tablas.
Frase de Introducción como Guía
Siempre usa una frase introductoria antes de una lista para definir su contenido. Proporciona contexto y une los elementos.
Ejemplos de frases de introducción:
- Realiza las siguientes acciones para inicializar:
- Parámetros de la función principal:
- Componentes del sistema requeridos:
Reglas para formarlas:
- Coloca un término unificador (acciones, parámetros, pasos) cerca del final.
- Evita especificar el número de elementos: puede quedar desactualizado con los cambios.
- Si no encaja un término específico, usa genéricos: elemento, parte, paso.
Esto asegura consistencia y facilita la lectura.
Frases Nominales para la Consistencia
Expresa los elementos de la lista como frases nominales. Esto crea una estructura uniforme y mejora la legibilidad. Ejemplo de transformación:
Incorrecto: El proceso consiste en: limpieza, preparación, envío.
Correcto: El proceso consiste en los siguientes pasos: limpieza, preparación, envío.
Todas las líneas deben ser gramaticalmente consistentes, sin mezclar fragmentos de oraciones y oraciones completas.
Evita Repeticiones en los Elementos
Las palabras repetidas al inicio de los elementos de lista crean un efecto de loro. Mueve la palabra común a la frase de introducción.
Ejemplo:
Incorrecto:
- Biblioteca A
- Biblioteca B
- Biblioteca C
Correcto: Instala las siguientes bibliotecas:
- A
- B
- C
Esto acorta el texto y enfoca en los detalles clave.
Listas de un Solo Elemento
Las listas independientes con un solo elemento rompen la uniformidad y sugieren errores de formato. Integra el elemento en la frase de introducción.
Ejemplo: En lugar de una lista que diga 'Parámetro de entrada: user_id', escribe: 'El parámetro de entrada user_id es el identificador del usuario'.
Puntuación en las Listas
Mantén la consistencia:
- Las líneas que comienzan con mayúscula terminan con punto.
- Las líneas en minúscula terminan con punto y coma.
Para elementos de varios párrafos, usa el primer estilo. Esto sigue los estándares de documentación técnica.
Reglas para Listas Anidadas
El anidamiento simplifica estructuras jerárquicas pero exige disciplina.
Niveles de Numeración:
- Nivel 1: 1, 2, 3
- Nivel 2: 1.1, 1.2
- Nivel 3: 1.1.1, 1.1.2
Evita letras y números romanos: complican la navegación.
Límite de Anidamiento: No más de 5 niveles. Si es necesario, divide en subsecciones. Se recomiendan cuatro niveles para una legibilidad óptima.
Después de Listas Sin Orden: No reanudes la numeración. Esto evita ambigüedades en la numeración.
Ejemplo de una estructura problemática:
- Nivel 1
1.1. Nivel 2
- Sin orden
1.1.1? // Incierto
Puntos Clave
- Usa listas numeradas solo para secuencias; listas sin orden para conjuntos.
- Frase de introducción con un término unificador obligatoria: sin cantidad especificada.
- Frases nominales y sin repeticiones en los elementos.
- Máximo 5 niveles de anidamiento; la numeración no continúa después de marcadores de viñetas.
- Puntuación: punto para líneas con mayúscula, punto y coma para minúsculas.
Las listas mejoran la escaneabilidad en textos técnicos como documentación, guías y artículos. Seguir estas reglas minimiza la carga cognitiva para desarrolladores mid/senior y especialistas técnicos.
— Editorial Team
Aún no hay comentarios.