Saltar a contenido

1.2.-Documentación

1.2. Documentación de software y herramientas

Idea principal

La documentación permite que las personas usuarias y los equipos técnicos comprendan, instalen, utilicen y mantengan una aplicación. Para que sea útil, hay que elegir el tipo de contenido, el formato y las herramientas según quién vaya a consultarla y para qué.

Una aplicación web no termina cuando funciona en el equipo de quien la programa. También hay que explicar cómo se instala, qué necesita para ejecutarse, cómo se utiliza y cómo se mantiene. Esta información facilita el despliegue, la colaboración y la continuidad del proyecto cuando cambian sus integrantes o sus requisitos.

En este apartado aprenderás a distinguir los principales tipos de documentación y a relacionarlos con herramientas de generación. El objetivo no es memorizar nombres, sino seleccionar una solución que encaje con el contenido que se quiere explicar y con las personas que lo necesitan.

Este punto amplía contenidos que ya has trabajado en otros módulos:

Este tema contribuye al RA 6 del módulo y trabaja los criterios de evaluación CE 6.a, CE 6.b, CE 6.c y CE 6.d. La tabla recoge literalmente los descriptores de la normativa:

Código Descripción
RA 6 Elabora la documentación de la aplicación web evaluando y seleccionando herramientas de generación de documentación, control de versiones y de integración continua.
CE 6.a Se han identificado diferentes herramientas de generación de documentación.
CE 6.b Se han documentado los componentes software utilizando los generadores específicos de las plataformas.
CE 6.c Se han utilizado diferentes formatos para la documentación.
CE 6.d Se han utilizado herramientas colaborativas para la elaboración y mantenimiento de la documentación.

Leer el tema ayuda a reconocer herramientas, formatos y decisiones. Para demostrar que sabes utilizarlos y mantener documentación en equipo, tendrás que aplicarlos en la práctica asociada.

Qué deberías saber al terminar

Al acabar este tema deberías poder:

  • distinguir la documentación para personas usuarias, equipos técnicos y desarrolladores;
  • explicar la diferencia entre un formato como Markdown y un generador como MkDocs o Dokka;
  • seleccionar una herramienta según el lenguaje, el tipo de documentación y el formato de salida;
  • describir un flujo básico para redactar, generar, revisar y publicar documentación.

Mapa del tema

Seguiremos esta secuencia:

  1. qué información se documenta y quién la consulta;
  2. qué formatos y herramientas se pueden utilizar;
  3. cómo se documenta un componente del código;
  4. cómo organizar y generar la documentación de un proyecto;
  5. qué recomendaciones ayudan a mantenerla útil y fiable.

1. Qué documentamos y para quién

La documentación de software es el conjunto de materiales que explica qué hace una aplicación, cómo está construida y cómo se utiliza o mantiene. Debe ayudar a encontrar respuestas sin depender de que una persona concreta esté disponible.

Como punto de partida, piensa en estas tres preguntas:

  1. ¿Qué hace el programa? Describe su propósito, sus funcionalidades y sus requisitos.
  2. ¿Cómo está hecho y por qué? Explica su arquitectura, sus componentes, las decisiones de diseño y las tecnologías empleadas.
  3. ¿Cómo se instala, se usa o se mantiene? Incluye las instrucciones necesarias para las personas usuarias, administradoras o desarrolladoras.

Documentar no es comentar cada línea

Los comentarios del código explican aspectos concretos de su implementación. La documentación del proyecto también puede incluir guías de uso, requisitos, diseño, pruebas, instalación, configuración y notas de versión.

Según su audiencia y propósito, encontramos tres grupos habituales:

Tipo A quién ayuda Contenidos frecuentes
Documentación para personas usuarias Quienes utilizan la aplicación. Manuales, guías de inicio rápido, preguntas frecuentes (FAQ), tutoriales y vídeos.
Documentación técnica Quienes diseñan, integran, prueban o administran el sistema. Requisitos funcionales y no funcionales, arquitectura, diagramas, API, integración y procedimientos de prueba.
Documentación para desarrolladores Quienes programan, amplían o mantienen el proyecto. Documentación de clases y funciones, guía de estilo, configuración del entorno, instalación, contribución y cambios de cada versión.

También se habla de documentación interna y externa. Esta clasificación describe dónde se mantiene, no a quién va dirigida:

Clasificación Ejemplos Uso habitual
Interna, junto al código KDoc, Javadoc y docstrings dentro de los ficheros fuente. Explicar componentes y permitir que un generador cree documentación de API.
Externa, fuera del código fuente README.md, manuales, guías de despliegue y wikis. Explicar el uso, la instalación, la arquitectura o la colaboración en el proyecto.

Una misma documentación puede combinar ambos enfoques: por ejemplo, una API puede generarse a partir de comentarios del código y publicarse como páginas HTML para que la consulte el equipo. Ningún manual sustituye a la documentación de componentes, ni al revés: se complementan.

Un proyecto web de clase

Una persona que solo quiere probar la aplicación necesita saber cómo iniciarla y qué datos introducir. Otra que vaya a mantenerla necesita, además, conocer sus dependencias, la estructura, las pruebas y la forma de configurar el entorno. Un único comentario en el código no resuelve las necesidades de ambas.

Un README.md suele servir como puerta de entrada al repositorio. Puede presentar el proyecto, indicar requisitos e instalación, mostrar un ejemplo de uso y enlazar guías más detalladas, licencia o instrucciones para contribuir. No es necesario convertirlo en un manual interminable: conviene que oriente a quien llega por primera vez.

2. Formatos y herramientas de documentación

Antes de elegir una herramienta, aclara qué quieres generar. KDoc y Markdown son formatos o convenciones para escribir contenido; Dokka y MkDocs son generadores que procesan ese contenido. Una herramienta no decide por sí sola qué información es correcta ni reemplaza la revisión del equipo.

2.1. Documentación generada desde el código

Estos formatos permiten describir elementos del código fuente, como funciones, clases, parámetros y excepciones. Un generador los convierte en páginas o ficheros navegables.

Formato o herramienta Lenguajes y contenido de entrada Uso y salida habitual
KDoc Kotlin; comentarios /** ... */ con etiquetas como @param, @return y @throws. Convención de documentación de Kotlin; se procesa normalmente con Dokka.
Dokka KDoc y proyectos Kotlin/JVM. Genera documentación navegable en HTML y, según la configuración, en formatos como Markdown o Jekyll. Se integra con Gradle.
Javadoc Java; comentarios de documentación /** ... */ y etiquetas como @param, @return y @throws. La herramienta javadoc genera páginas HTML, habituales en bibliotecas y API de Java.
Doxygen C, C++, Java, Python, PHP y otros lenguajes, con sintaxis configurable. Genera documentación de referencia en HTML, XML o LaTeX; el PDF puede requerir procesar la salida LaTeX. Es útil en proyectos multilenguaje, aunque su configuración inicial es más amplia.
JSDoc JavaScript; comentarios con etiquetas como @param y @returns. Genera documentación de funciones, clases y módulos JavaScript, normalmente en HTML.
PyDoc Python; módulos, clases, funciones y docstrings. Módulo incluido en Python que permite consultar documentación en la terminal o generar HTML.
Sphinx Documentación escrita, especialmente habitual en proyectos Python; admite extensiones y varios formatos de marcado. Construye sitios de documentación y otros formatos de salida, según los generadores configurados.

2.2. Manuales, sitios y formatos de intercambio

Formato o herramienta Qué es Cuándo puede servir
Markdown Formato de texto ligero, independiente del lenguaje. Se usa en README.md, manuales, notas técnicas, wikis y blogs. Para redactar documentación legible en texto plano y reutilizarla en plataformas como GitHub, GitLab o Bitbucket. Se puede convertir a HTML, PDF o DOCX con herramientas como Pandoc.
MkDocs Generador de sitios estáticos a partir de archivos Markdown y de una configuración, normalmente mkdocs.yml. Para manuales, guías de usuario y documentación de proyectos. Produce un sitio HTML que se puede publicar en GitHub Pages o en un servidor propio. No extrae por sí solo la API del código.
Docusaurus Generador de sitios de documentación basado en tecnologías web y contenido Markdown o MDX, iniciado en Facebook. Para sitios con navegación, versiones, traducciones y extensiones. La configuración incluye archivos como docusaurus.config.js y, según el proyecto, sidebars.js.
Wiki de GitHub Espacio de páginas Markdown asociado a un repositorio. Para elaborar y mantener notas o guías colaborativamente; no genera automáticamente la documentación de API del código.
Pandoc Conversor entre formatos de documentos. Para transformar Markdown y otros formatos a HTML, DOCX, PDF u otras salidas; algunas conversiones necesitan programas auxiliares.

Cuando la documentación vive en el mismo repositorio que el código, el equipo puede proponer cambios mediante pull requests y revisarlos antes de integrarlos. Una wiki puede resultar más cómoda para editar páginas sin modificar el código. En ambos casos hay que acordar quién puede editar, revisar y publicar la información.

No confundas formato, contenido y generador

Markdown es una forma de escribir. MkDocs transforma ficheros Markdown en un sitio web, pero no sabe por sí solo cómo funciona el código. KDoc describe componentes Kotlin y Dokka procesa esa documentación. En Java, Javadoc también nombra la herramienta y el estilo de comentarios que esta procesa.

La elección depende del contenido que se quiere mantener:

  • Documentar una API de Kotlin: escribir KDoc y generar las páginas con Dokka.
  • Documentar código Java: usar comentarios Javadoc y ejecutar javadoc.
  • Documentar código de varios lenguajes: valorar Doxygen, revisando antes qué lenguajes y convenciones necesita el proyecto.
  • Crear una guía de instalación o un manual: redactar en Markdown y usar MkDocs, Docusaurus o una wiki.
  • Convertir el mismo contenido a varios formatos: valorar Pandoc y comprobar qué dependencias necesita cada salida.

La documentación de Python en docs.python.org es un ejemplo de referencia amplio; no implica que esté generada necesariamente con MkDocs. Para escoger una herramienta, fíjate en la documentación oficial y en el proceso real de generación del proyecto.

3. Ejemplo: documentar una función Kotlin con KDoc

Este ejemplo conserva la documentación del código y añade una condición de entrada y la excepción que puede producir. Así, quien consulte la función sabe qué valor debe pasar y qué resultado esperar:

import kotlin.math.PI

/**
 * Calcula el área de un círculo a partir de su radio.
 *
 * @param radio Radio del círculo en centímetros; debe ser no negativo.
 * @return Área del círculo en centímetros cuadrados.
 * @throws IllegalArgumentException si el radio es negativo.
 */
fun areaCirculo(radio: Double): Double {
    require(radio >= 0) { "El radio no puede ser negativo" }
    return PI * radio * radio
}

KDoc aporta la información en el código fuente. Al ejecutar Dokka en el proyecto, se puede generar una página HTML que muestre la descripción, el parámetro, el valor de retorno y la excepción. El generador no comprueba que la explicación sea completa o verdadera: esa responsabilidad sigue siendo del equipo.

El mismo principio se aplica en Java con Javadoc y en Python con docstrings y herramientas como PyDoc o Sphinx. Cambia la sintaxis; el propósito es ayudar a usar correctamente los componentes.

4. Flujo para documentar un proyecto

La documentación se crea y se revisa durante la evolución del software, no solo al final. Un proceso sencillo empieza identificando a las personas destinatarias y termina comprobando que la documentación publicada corresponde a la versión del proyecto.

flowchart TD
  A["Identificar audiencia y tareas"] --> B["Elegir contenidos y formatos"]
  B --> C["Organizar páginas y navegación"]
  C --> D["Redactar guías y documentar componentes"]
  D --> E["Generar una versión local"]
  E --> F{"¿Se entiende y se genera sin errores?"}
  F -->|No| G["Corregir contenido o configuración"]
  G --> E
  F -->|Sí| H["Versionar y publicar"]
  H --> I["Actualizar junto con cada cambio"]
  I --> A

En cada fase conviene comprobar algo distinto:

  1. Identificar audiencia y tareas: concreta quién va a consultar la guía y qué necesita hacer. Una persona usuaria y quien administra el servidor no buscan las mismas instrucciones.
  2. Elegir contenidos y formatos: incluye los requisitos y las pruebas si ayudan a verificar el comportamiento; añade arquitectura, API o pasos de despliegue cuando sean necesarios para el proyecto.
  3. Organizar páginas y navegación: separa, por ejemplo, la guía de uso, la guía de desarrollo, la referencia de API y las instrucciones de instalación.
  4. Redactar y generar: utiliza ejemplos reproducibles, estructura clara y los generadores adecuados para el código que se quiera describir.
  5. Revisar, versionar y publicar: prueba los enlaces y los comandos, genera el sitio y comprueba los permisos antes de publicarlo. Si cambia el comportamiento de la aplicación, revisa la documentación relacionada.

Una estructura inicial para una guía Markdown puede ser:

README.md
docs/
├── inicio-rapido.md
├── guia-usuario/
├── guia-desarrollo/
└── api/

La organización concreta depende del tamaño del proyecto. En MkDocs, la navegación y el tema se configuran en mkdocs.yml; en Docusaurus se suele configurar el sitio y la navegación mediante docusaurus.config.js y archivos de barras laterales; JSDoc permite definir entradas y directorio de salida en jsdoc.json.

5. Puesta en marcha y publicación

Los comandos exactos cambian con la versión y la configuración del proyecto. Estos ejemplos muestran el ciclo habitual de instalar o crear, previsualizar y generar. Ejecútalos en un entorno de prueba y consulta la documentación oficial antes de publicarlos.

5.1. MkDocs

python -m pip install mkdocs
mkdocs new mi-manual
cd mi-manual
mkdocs serve
mkdocs build

mkdocs serve inicia una previsualización local para revisar el contenido; mkdocs build comprueba la configuración y genera el sitio estático en la carpeta site/. Para publicarlo en GitHub Pages se puede configurar un flujo de integración continua o utilizar mkdocs gh-deploy con los permisos y la configuración adecuados. El comando de publicación no sustituye la revisión del resultado.

5.2. Docusaurus

npx create-docusaurus@latest mi-sitio classic
cd mi-sitio
npm start
npm run build

npm start inicia el servidor local de desarrollo y npm run build genera la versión preparada para publicar. El proyecto puede ajustar el título, la navegación, los temas y las traducciones desde sus ficheros de configuración.

5.3. JSDoc

npm install --save-dev jsdoc
npx jsdoc src -r -d docs/api

El comando recorre el código de src y guarda la documentación generada en docs/api. Para que las páginas expliquen el propósito, los parámetros y los resultados, el código debe incluir comentarios JSDoc útiles.

6. Buenas prácticas

Para que la documentación sirva de verdad, conviene:

  • Escribir para una audiencia concreta: usar lenguaje accesible para las personas usuarias y explicar los tecnicismos cuando sean necesarios.
  • Mantenerla junto al proyecto: versionar los ficheros y revisar sus cambios junto con los cambios de código o configuración a los que afectan.
  • Usar ejemplos verificables: indicar requisitos, comandos y resultados esperados; comprobarlos en un entorno limpio antes de publicar.
  • Estructurar y facilitar la búsqueda: utilizar títulos descriptivos, navegación coherente, tablas breves, capturas con texto alternativo y enlaces a información más detallada.
  • Proteger la información: revisar permisos y retirar credenciales, datos personales o configuraciones privadas antes de generar o publicar el sitio.
  • Automatizar cuando aporte valor: integrar la generación en CI/CD permite detectar enlaces o construcciones rotas, pero no garantiza por sí sola que el contenido sea correcto.

7. Errores frecuentes

Error frecuente Por qué ocurre Cómo evitarlo
Confundir Markdown con un generador. Markdown describe el formato del texto, pero no construye por sí solo un sitio ni extrae documentación del código. Elegir además un generador o visor, como MkDocs, Docusaurus o Pandoc, según la salida que se necesite.
Creer que KDoc o Javadoc generan automáticamente documentación completa. Se confunde la sintaxis de los comentarios con la herramienta que los procesa. Escribir comentarios útiles y ejecutar Dokka o javadoc; después, revisar el resultado.
Usar una herramienta de manuales para extraer la API del código. No se distingue entre escribir páginas externas y procesar comentarios del código fuente. Combinar herramientas: por ejemplo, KDoc con Dokka para la API y Markdown con MkDocs para las guías.
Publicar instrucciones sin probarlas. Se redactan comandos de memoria o para un entorno distinto. Seguir los pasos desde un entorno limpio y actualizar requisitos, versiones y resultados esperados.
Dejar la documentación desactualizada o publicar información privada. El código cambia más a menudo que las guías, o no se revisan permisos y contenidos. Incluir la documentación en las revisiones y comprobar secretos, datos y permisos antes de desplegarla.

8. Resumen

En este tema has aprendido que:

  • la documentación explica el propósito, el diseño, el uso y el mantenimiento de un programa para distintas audiencias;
  • la documentación para usuarios, la documentación técnica y la de desarrollo se complementan, al igual que la documentación interna y la externa;
  • KDoc, Javadoc, Doxygen, JSDoc, PyDoc y Sphinx ayudan a documentar código, mientras que Markdown, MkDocs, Docusaurus, las wikis y Pandoc sirven para redactar, publicar o transformar otros contenidos;
  • una documentación útil se organiza, se genera, se revisa, se versiona y se actualiza con el software.

Idea clave

Elige la herramienta por el contenido que necesitas mantener y por quién lo va a consultar; después comprueba que la documentación generada explica de forma fiable la versión real del proyecto.

9. Para seguir practicando

  • Realiza la práctica de documentación y GitHub Actions: identifica el generador, el formato de salida y las tareas que ejecuta el flujo.
  • Revisa un README.md de un proyecto conocido y comprueba si una persona nueva podría instalarlo y ejecutar un ejemplo.
  • Documenta una función pública de Kotlin con KDoc y genera su documentación con Dokka; después, verifica que los parámetros, el resultado y las excepciones se entienden.

Bibliografía y fuentes

Presentación