Cómo documentar un proyecto con Markdown

Una buena documentación es esencial para cualquier proyecto de software. Markdown se ha convertido en el estándar para escribir documentación técnica gracias a su simplicidad y compatibilidad con plataformas como GitHub.

Estructura de la documentación

Un proyecto bien documentado suele incluir los siguientes archivos:

Archivos esenciales

Carpeta docs/

Para documentación más extensa, es habitual crear una carpeta docs/ con archivos organizados por temas:

docs/
├── getting-started.md
├── installation.md
├── configuration.md
├── api/
│   ├── endpoints.md
│   └── authentication.md
├── guides/
│   ├── deployment.md
│   └── troubleshooting.md
└── faq.md

Ejemplo completo de CONTRIBUTING.md

El archivo CONTRIBUTING.md establece las reglas para que otros desarrolladores colaboren en tu proyecto. Sin el, cada persona contribuye de forma diferente y mantener el proyecto se vuelve caotico. Aqui tienes un ejemplo completo que puedes adaptar:

# Guia para contribuir

Gracias por tu interes en contribuir a este proyecto. Esta guia
te ayudara a entender el proceso.

## Requisitos previos

- Node.js 18 o superior
- npm 9 o superior
- Git

## Configurar el entorno de desarrollo

1. Haz un fork del repositorio
2. Clona tu fork:
   git clone https://github.com/tu-usuario/proyecto.git
3. Instala las dependencias:
   npm install
4. Crea una rama para tu cambio:
   git checkout -b feature/descripcion-del-cambio

## Convenciones de codigo

- Usamos ESLint para mantener un estilo consistente
- Ejecuta `npm run lint` antes de hacer commit
- Los nombres de variables y funciones en camelCase
- Los componentes de React en PascalCase

## Convenciones de commits

Seguimos Conventional Commits:

- `feat:` para nuevas funcionalidades
- `fix:` para correccion de errores
- `docs:` para cambios en documentacion
- `refactor:` para reestructuracion de codigo
- `test:` para anadir o modificar tests

Ejemplo: `feat: agregar filtro de busqueda por etiquetas`

## Proceso de Pull Request

1. Asegurate de que todos los tests pasan: `npm test`
2. Actualiza la documentacion si es necesario
3. Abre un Pull Request contra la rama `main`
4. Describe los cambios en detalle en la descripcion del PR
5. Espera la revision de al menos un mantenedor

## Reportar errores

Usa la plantilla de issues e incluye:

- Descripcion clara del error
- Pasos para reproducirlo
- Comportamiento esperado vs. actual
- Version del proyecto y sistema operativo

## Codigo de conducta

Este proyecto sigue el [Contributor Covenant](https://www.contributor-covenant.org/).
Tratamos a todos los participantes con respeto.

Herramientas para documentacion

Existen generadores especializados en documentacion tecnica. Cada uno tiene sus fortalezas segun el tipo de proyecto y el lenguaje que uses.

Docusaurus

Docusaurus esta creado por Meta y es ideal para documentacion de proyectos de codigo abierto. Usa React internamente y soporta MDX, lo que te permite incluir componentes interactivos dentro de la documentacion.

npx create-docusaurus@latest mi-docs classic
cd mi-docs
npm start

Esto levanta un sitio de documentacion completo en http://localhost:3000 con busqueda integrada, versionado de documentacion y soporte para multiples idiomas.

MkDocs

MkDocs es un generador de documentacion escrito en Python. Es especialmente popular en proyectos Python y ciencia de datos. Con el tema Material, obtienes una documentacion visualmente profesional.

pip install mkdocs mkdocs-material
mkdocs new mi-docs
cd mi-docs
mkdocs serve

La configuracion se hace en un unico archivo mkdocs.yml donde defines la navegacion, el tema y los plugins. Es uno de los generadores mas sencillos de configurar.

Docsify

Docsify tiene una ventaja unica: no necesita compilacion. Carga los archivos Markdown directamente en el navegador y los renderiza en tiempo real. Esto lo hace perfecto para documentacion que cambia frecuentemente.

GitBook

GitBook es una plataforma completa para crear documentacion colaborativa. Ofrece un editor visual que permite a personas no tecnicas contribuir a la documentacion sin tocar Markdown directamente.

VitePress

VitePress es el sucesor espiritual de VuePress, construido sobre Vite. Es extremadamente rapido tanto en desarrollo como en compilacion, y es la opcion recomendada para proyectos del ecosistema Vue.

Buenas practicas

Sigue estas buenas practicas para documentar tu proyecto:

• Manten la documentacion junto al codigo: Facilita las actualizaciones.
• Usa ejemplos de codigo: Ayudan a entender como usar tu proyecto.
• Incluye capturas de pantalla: Especialmente para interfaces de usuario.
• Versiona la documentacion: Usa Git para rastrear cambios.
• Automatiza: Genera documentacion de API a partir del codigo fuente.
• Revisa regularmente: Documentacion desactualizada es peor que ninguna documentacion.

Documentacion automatica

Escribir documentacion manualmente para cada funcion, clase y metodo es tedioso y propenso a quedar desactualizado. Las herramientas de documentacion automatica extraen los comentarios del codigo fuente y generan documentacion navegable en HTML.

JSDoc (JavaScript)

JSDoc lee los comentarios con formato especial en tu codigo JavaScript y genera una referencia de API completa:

/**
 * Calcula el precio total con impuestos
 * @param {number} precio - Precio base del producto
 * @param {number} impuesto - Porcentaje de impuesto (ej: 0.21)
 * @returns {number} Precio total con impuesto incluido
 */
function calcularTotal(precio, impuesto) {
  return precio * (1 + impuesto);
}

Para generar la documentacion, instala JSDoc y ejecuta:

npm install -D jsdoc
npx jsdoc src/ -d docs/api

TypeDoc (TypeScript)

TypeDoc es el equivalente de JSDoc para proyectos TypeScript. Aprovecha los tipos del lenguaje para generar documentacion mas rica sin necesidad de tantas anotaciones manuales:

npm install -D typedoc
npx typedoc --out docs/api src/index.ts

Sphinx (Python)

Sphinx es el estandar de facto para documentar proyectos Python. Lo usan Django, Flask, NumPy y casi todos los proyectos importantes del ecosistema. Soporta reStructuredText y Markdown (con la extension MyST):

pip install sphinx
sphinx-quickstart docs
cd docs
make html

Mantener la documentacion actualizada

La documentacion desactualizada es peor que no tener documentacion, porque genera falsas expectativas y frustra a los usuarios. Estas son estrategias practicas para mantenerla al dia:

Incluir documentacion en los Pull Requests

Establece como regla del equipo que cualquier PR que cambie funcionalidad debe actualizar la documentacion correspondiente. Anade un check en tu plantilla de PR que pregunte: "Se ha actualizado la documentacion?".

Tests de documentacion

Algunas herramientas permiten ejecutar los ejemplos de codigo que aparecen en la documentacion como tests automaticos. En Python, doctest hace exactamente esto. En JavaScript, puedes usar herramientas como markdown-doctest para verificar que los ejemplos de codigo siguen funcionando.

Revisiones periodicas programadas

Reserva tiempo cada mes o cada sprint para revisar la documentacion. Busca comandos obsoletos, enlaces rotos y capturas de pantalla que ya no correspondan con la interfaz actual. Herramientas como markdown-link-check detectan enlaces rotos automaticamente:

npx markdown-link-check docs/**/*.md

Documentacion como codigo

Trata la documentacion con el mismo rigor que el codigo: usa linters como markdownlint para mantener un formato consistente, revisa los cambios en PR y despliega automaticamente cuando se fusionan cambios en la rama principal.