Skip to main content

Principios de una Buena Documentación

⏱ Dedicación recomendada: 0 minutos
Esto considera el contenido visible y relevante, e ignora texto colapsado o marcado como opcional.

La documentación es más que una simple descripción del código: es una conversación continua entre quienes crean software y quienes lo usan. En el contexto del desarrollo de bibliotecas, escribir buena documentación no es opcional: es esencial. A medida que otras personas integran, extienden o dependen de tu trabajo, la claridad, accesibilidad y utilidad de la documentación se vuelven tan importantes como el código mismo.

Esta guía explora los principios fundamentales para escribir documentación efectiva, mantenible y centrada en lxs usuarixs. Desde cuándo y cómo escribirla, hasta cómo hacerla escaneable, completa y estéticamente agradable, el objetivo es ayudarte a construir documentación que no solo explique, sino que acompañe y guíe.

Porque al final del día, el mejor código es aquel que otras personas pueden entender y usar con confianza.

✍️ Documentación precursora​

Empieza a documentar antes de comenzar a desarrollar.

Antes de escribir código, reflexiona sobre cómo se utilizará y documenta algunos ejemplos de uso. Esto no solo te ayudará a diseñar una API más clara, sino también a detectar posibles problemas antes de que se conviertan en obstáculos. La documentación temprana también facilita la retroalimentación de tus colegas y las decisiones grupales, guiando mejor tu trabajo desde el inicio.

Relación con testing

Escribir tests puede servir como una manera de documentación temprana, ya que los tests describen cómo se espera que funcione el código. La documentación y los tests pueden complementarse mutuamente para proporcionar una visión más completa del software.

👥 Documentación participativa​

Incluye a todas las personas en el proceso de documentación, desde quienes desarrollan hasta quienes usan el software.

Integra la documentación en el flujo de trabajo estándar de desarrollo y evita que solo un grupo reducido sea responsable de ella. Lxs desarrolladorxs tienen acceso directo a la información más demandada, por lo que su participación fomenta una cultura de documentación. Además, lxs usuarixs de la documentación deben tener formas claras de involucrarse, como proporcionando comentarios o sugerencias. Permitirles editar directamente, como en un wiki, puede ser útil, pero debe balancearse con la necesidad de supervisión editorial.

🔁 ARID: Aceptar algo de repetición​

Accept (some) Repetition In Documentation.

Si bien el principio de "Don't Repeat Yourself" (DRY) es fundamental para escribir buen código, aplicarlo de manera estricta en la documentación no es práctico. Parte de la lógica de negocio implementada en el código debe ser repetida en la documentación. El enfoque ARID busca mantener las cosas lo más secas posible, pero reconoce que inevitablemente se necesitará algo de "humedad" para lograr una buena documentación. Mantener esta realidad presente puede ayudar a lxs desarrolladorxs a recordar que la documentación necesita actualizarse junto con el código.

👀 Escaneable​

Estructura el contenido para ayudar a lxs lectorxs a identificar y saltarse conceptos que ya comprenden o que no son relevantes para sus preguntas inmediatas.

Enterrar conceptos en prosa y verborrea demanda más tiempo de lxs lectorxs que buscan respuestas específicas. Ahorra tiempo escribiendo como un periódico, no como una novela.

Específicamente:

  • Encabezados: deben ser descriptivos y concisos.
  • Hipervínculos: deben rodear palabras que describan el enlace en sí (y nunca frases como "haz clic aquí" o "esta página").
  • Párrafos y elementos de listas: deben comenzar con conceptos identificables lo más pronto posible.

🧩 Ejemplar: Usa ejemplos y tutoriales​

Incluye (algunos) ejemplos y tutoriales en el contenido.

Muchxs lectorxs buscan primero ejemplos para obtener respuestas rápidas, por lo que incluirlos les ayudará a ahorrar tiempo. Intenta escribir ejemplos para los casos de uso más comunes, pero no para todo. Demasiados ejemplos pueden hacer que la documentación sea menos escaneable. Además, considera separar los ejemplos y tutoriales de la información de referencia más densa para facilitar aún más que lxs lectorxs puedan hojear rápidamente.

📏 Consistente​

Utiliza un lenguaje y una estructura uniformes en toda la documentación.

Cuantxs más editorxs de contenido tengas, más importante se vuelve tener una guía de estilo para facilitar la consistencia. La consistencia también ayuda a que la documentación sea fácil de hojear y estéticamente agradable.

🔄 Siempre actualizada​

Considera que una documentación incorrecta es peor que no tener documentación.

Cuando el software cambia más rápido que su documentación, lxs usuarixs sufren. Es importante mantenerla actualizada. Esfuérzate por escribir contenido que no dependa de una versión específica, lo que reduce la necesidad de mantenimiento. Algunos usuarixs seguirán usando versiones anteriores del software, por lo que es crucial que la plataforma de documentación soporte versiones anteriores de manera adecuada.

📍 Cercana al código​

Almacena las fuentes lo más cerca posible del código que documentan.

Proporciónales a lxs desarrolladorxs sistemas que les permitan hacer cambios en la documentación al mismo tiempo que modifican el código. Una forma es almacenar el contenido de la documentación en bloques de comentarios dentro del código fuente de la aplicación. Otra opción es guardarlo en archivos de texto separados pero dentro del mismo repositorio que el código fuente. El objetivo es fusionar, en la medida de lo posible, los flujos de trabajo de desarrollo y documentación.

🚫 Única: Sin redundancia entre fuentes​

Elimina la superposición de contenido entre fuentes separadas.

Almacenar contenido en diferentes fuentes está bien, siempre que el alcance de cada fuente esté claramente definido y no se superponga con otras. El objetivo es evitar la necesidad de mantenimiento paralelo (o, peor aún, la falta de mantenimiento) de la misma información en varias ubicaciones.

🔎 Descubrible​

Guía a lxs usuarixs de forma intuitiva hacia las publicaciones a través de todos los caminos posibles.

Intenta identificar todos los lugares donde lxs usuarixs podrían buscar documentación y, en cada uno de esos lugares, inserta indicaciones útiles para que puedan encontrarla. La documentación no tiene que estar en todos esos sitios, pero sí debería haber referencias o enlaces hacia ella.

Si un manual de usuario se publica en el bosque y nadie está allí para leerlo, ¿existe realmente? Según el principio de descubribilidad, la respuesta es "no".

🔗 Direccionable​

Proporciona a lxs lectorxs direcciones que enlacen directamente con el contenido a un nivel granular.

La capacidad de referenciar secciones específicas dentro de un cuerpo de documentación facilita una comunicación productiva sobre el contenido, incluso con unx mismx. Estas referencias pueden ser en forma de URLs, números de página, u otros formatos según el medio de publicación. Lxs lectorxs pueden querer marcar ciertas secciones, compartirlas con otrxs usuarixs, o brindar retroalimentación a lxs autores. Cuanto más granular y accesible sea esta capacidad, mejor.

🏗 Acumulativa​

El contenido debe estar ordenado de manera que cubra primero los conceptos previos o fundamentales.

¿Puede unx lectorx seguir toda tu documentación de manera lineal, de principio a fin, sin confundirse? Si es así, la documentación es "acumulativa", lo cual es ideal, pero no siempre posible. Es algo que se debe buscar, especialmente en tutoriales y ejemplos. Si has separado los tutoriales y ejemplos de la documentación de referencia, colócalos primero. Luego, la sección de referencia puede ordenarse alfabéticamente o por temas sin considerar los requisitos previos.

El objetivo del orden acumulativo no es que lxs lectorxs sigan la documentación de manera lineal, sino ayudarles a enfocar su búsqueda de información al llenar vacíos en su conocimiento. Si alguien comienza a leer la documentación con algo de conocimiento previo en el punto medio, probablemente "retrocederá" cuando se confunda.

📚 Completa​

Dentro de cada publicación, cubre los conceptos por completo o no los cubras en absoluto.

Imagina la documentación de software como un mapa de un vecindario. Si el mapa muestra carreteras, lxs lectorxs esperarán que muestre todas las carreteras (de un mismo tipo). Tal vez no muestre vías ferroviarias, por ejemplo. Quien busque vías ferroviarias notará su ausencia y buscará otro mapa, pero el primero sigue siendo "completo" en cuanto a carreteras. "Completo" no significa describir todas las características del terreno, sino que, para las características elegidas, debe describirlas todas. Un mapa que muestra solo la mitad de los hidrantes de una zona es peor que uno que no muestra ninguno.

Si publicas documentación incompleta, debes ser cauteloso. Para evitar confundir a lxs lectorxs, es fundamental aclarar desde el principio que un concepto solo está cubierto parcialmente.

✨ Bella 💅✨​

El estilo visual debe ser intencional y estéticamente agradable.

La estética no es importante para todxs, pero (consciente o inconscientemente) algunxs lectorxs tendrán dificultades para sentirse cómodxs con documentación que carezca de atención al estilo visual. Incluso en documentación solo de texto, como la salida de --help, el estilo visual está presente en la forma de espaciado y capitalización. Si el estilo visual no es una prioridad para ti, considera pedir mejoras estilísticas a quienes sí les importe.

🚀 Ejemplo de guía de estilo para Kotlin​

1. Código en Markdown​

Al escribir fragmentos de código en la documentación, SIEMPRE utiliza la sintaxis adecuada de Markdown. Encierra todos los fragmentos de código con:

```
// ...
```

Esto asegura que el código sea legible y esté bien formateado.

2. Uso de la etiqueta @property para variables públicas​

Al documentar clases, PREFIERE usar la etiqueta @property para describir las variables públicas, en lugar de documentarlas dentro del cuerpo de la clase.

3. Uso preferido de enlaces de referencia​

PREFIERE utilizar enlaces de referencia (por ejemplo, [String]) en lugar de formateo monospace (por ejemplo, `String`) cuando hagas referencia a tipos u otros elementos importantes en la documentación.

4. Ejemplos de uso​

Cuando proporciones ejemplos de uso en los comentarios de docstring, sigue esta sintaxis:

/**
 * Descripción corta de la función.
 *
 * Descripción detallada de la función.
 *
 * ## Uso:
 * Detalles y escenarios de uso.
 *
 * ### Ejemplo 1: Descripción
 * ```kotlin
 * // código del ejemplo 1
 * ```
 * ### Ejemplo 2: Descripción
 * ```kotlin
 * // código del ejemplo 2
 * ```
 * @tags
 */
fun foo(params) = elements.forEach(action)

Nota Importante:​

Coloca los ejemplos antes de las @tags. Ejemplos de @tags incluyen @param, @return, @throws, etc.

🛠 Herramientas de Documentación​

Existen diversas herramientas que facilitan la creación y mantenimiento de documentación de calidad en distintos lenguajes de programación. A continuación, mencionamos algunas de las más populares:

🔵 Para Kotlin y Java​

  • Kdoc → Herramienta oficial para documentar Kotlin.
  • Javadoc → Estándar en Java, compatible con Kotlin.
  • Dokka → Genera documentación en HTML y Markdown, recomendado para Kotlin.

🐍 Para Python​

  • Sphinx → Compatible con reStructuredText y genera múltiples formatos.
  • MkDocs → Alternativa basada en Markdown.

📄 Para documentación basada en web​

  • Docusaurus → Basado en React, ideal para documentación técnica extensa.
  • Nextra → Basado en Next.js, excelente para proyectos modernos.
  • GitHub Wiki → Solución simple dentro de GitHub para documentar repositorios.

📚 Plataformas de documentación colaborativa​

  • GitBook → Ofrece edición colaborativa en la nube.
  • ReadTheDocs → Popular en proyectos open-source, automatiza la generación de docs.

Cada una de estas herramientas tiene sus propias fortalezas dependiendo del lenguaje o ecosistema de tu proyecto, así como las necesidades de personalización o formato de la documentación.

🎯 Conclusiones​

Una buena documentación no es un lujo ni una tarea secundaria: es una parte integral del desarrollo de bibliotecas y herramientas reutilizables. Acompaña al código en cada etapa de su ciclo de vida y permite que otras personas lo entiendan, lo usen y lo extiendan con confianza. Si el código es el qué, la documentación es el cómo y el por qué.

Más allá de describir funciones, la documentación comunica intenciones, promueve buenas prácticas, previene errores y fomenta comunidad.

🔑 Puntos clave​

  • Documenta desde el principio: los ejemplos tempranos aclaran tu API y mejoran el diseño.
  • Involucra a todas las personas posibles: documentación colectiva es mejor documentación.
  • Sé claro, consistente y escaneable: escribe para quien necesita respuestas.
  • Acepta algo de repetición, pero evita la redundancia entre fuentes.
  • Mantén la documentación cercana al código, versionada, actualizada y direccionable.
  • Asegúrate de que esté completa, acumulativa y estéticamente cuidada.

🧰 ¿Qué nos llevamos?​

Crear documentación efectiva es un acto de empatía técnica: se trata de anticipar lo que otras personas necesitan para entender tu trabajo. Al aplicar estos principios, no solo mejoras la calidad de tu biblioteca, sino también la experiencia de quienes la usan.

Porque un software bien documentado no solo funciona, sino que invita, enseña y perdura.

📖 Referencias​

🔥 Recomendadas​