Markdown para documentación técnica

Markdown se ha convertido en el estándar para documentación técnica. Las empresas más grandes del mundo (Google, Meta, Microsoft, Stripe) documentan sus proyectos con Markdown. En esta guía verás cómo crear documentación profesional desde cero, qué herramientas usar y qué buenas prácticas seguir.

Por qué Markdown para documentación

Versionable con Git

Los archivos .md son texto plano, lo que los hace perfectos para control de versiones. Puedes ver exactamente qué cambió, quién lo cambió y cuándo, con un simple git diff. Esto es imposible con Google Docs o Confluence.

Colaborativa

Cualquier persona con un editor de texto puede contribuir. No necesita licencias de software ni formación especial. Los pull requests permiten revisar cambios antes de publicarlos, igual que se revisa el código.

Portable

Si mañana decides cambiar de herramienta, tus archivos Markdown funcionan en cualquier otra. No estás atrapado en ningún ecosistema. El mismo contenido se puede usar en MkDocs, Docusaurus, VitePress o cualquier generador de sitios estáticos.

Automatizable

Puedes generar sitios web, PDFs y otros formatos automáticamente con CI/CD. Un push a main puede actualizar tu documentación en segundos.

Estructura de un proyecto de documentación

Una buena estructura de carpetas es la base de cualquier proyecto de documentación. Esta organización separa las guías de inicio, las guías avanzadas y la referencia de API, lo que facilita que tanto usuarios nuevos como experimentados encuentren lo que buscan:

docs/
  index.md                  # Página principal
  getting-started/
    installation.md         # Instalación
    quickstart.md           # Primeros pasos
    configuration.md        # Configuración
  guides/
    authentication.md       # Guías detalladas
    deployment.md
    troubleshooting.md
  api/
    overview.md             # Referencia de API
    endpoints.md
    errors.md
  contributing.md           # Cómo contribuir
  changelog.md              # Historial de cambios

Principios de organización

1. Agrupa por temática, no por tipo de documento.
2. Usa nombres descriptivos en los archivos (authentication.md en vez de auth.md).
3. Mantén una jerarquía plana: máximo 2-3 niveles de anidación.
4. Cada página, un tema: si una página cubre demasiado, divídela.

Tipos de documentación técnica

Documentación de API

La documentación de API debe ser clara, completa y con ejemplos reales. Cada endpoint necesita sus parámetros, la respuesta esperada y los posibles errores. Puedes usar nuestra plantilla de documentación de API como punto de partida.

## GET /api/users

Devuelve una lista de usuarios.

### Parámetros

| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| page | integer | No | Número de página (default: 1) |
| limit | integer | No | Resultados por página (default: 20) |
| search | string | No | Filtrar por nombre |

### Respuesta exitosa (200)

```json
{
  "data": [
    {
      "id": 1,
      "name": "Eduardo",
      "email": "eduardo@ejemplo.com"
    }
  ],
  "total": 150,
  "page": 1
}
```

### Errores

| Código | Descripción |
|---|---|
| 401 | No autenticado |
| 403 | Sin permisos |
| 500 | Error del servidor |

Guías de instalación

Las guías de instalación deben ser reproducibles paso a paso. Incluye siempre los requisitos previos con versiones mínimas y cada comando necesario. Un buen truco es probar la guía en un entorno limpio antes de publicarla.

## Requisitos previos

- Node.js >= 18.0
- npm >= 9.0
- PostgreSQL >= 14

## Instalación

1. Clona el repositorio:
   ```bash
   git clone https://github.com/ejemplo/proyecto.git

2. Instala las dependencias:

   npm install

3. Configura las variables de entorno:

   cp .env.example .env

4. Ejecuta las migraciones:

   npm run migrate

### Architecture Decision Records (ADRs)

Los ADRs documentan las decisiones técnicas importantes del proyecto: qué se decidió, por qué y qué alternativas se descartaron. Son especialmente valiosos cuando un nuevo miembro del equipo necesita entender por qué las cosas son como son.

````md
# ADR-001: Usar PostgreSQL como base de datos

## Estado
Aceptado

## Contexto
Necesitamos una base de datos relacional para el proyecto.
Los candidatos principales son PostgreSQL y MySQL.

## Decisión
Usaremos PostgreSQL por su robustez, soporte para JSON
y extensiones como PostGIS.

## Alternativas consideradas
- **MySQL**: descartada por menor soporte de tipos de datos avanzados.
- **MongoDB**: descartada porque nuestro modelo de datos es relacional.

## Consecuencias
- Necesitamos un servidor PostgreSQL en producción
- El equipo debe familiarizarse con PostgreSQL

READMEs

El README es la puerta de entrada a cualquier proyecto. Si tu proyecto no tiene un buen README, la mayoría de visitantes se irán sin probarlo. Consulta nuestra plantilla de README para empezar con una estructura sólida.

CHANGELOGs

El CHANGELOG documenta los cambios entre versiones. Es fundamental para que los usuarios sepan qué ha cambiado antes de actualizar. La convención más extendida es Keep a Changelog.

Herramientas para generar documentación

MkDocs + Material

Instalación:

pip install mkdocs-material

Después de instalar, ejecuta mkdocs new mi-docs para crear un proyecto nuevo, o mkdocs serve para ver la documentación en http://localhost:8000 con recarga automática.

Configuración básica (mkdocs.yml):

El archivo mkdocs.yml es el corazón de tu proyecto. Aquí defines el nombre del sitio, el tema visual, los plugins activos y la estructura de navegación:

site_name: Mi Documentación
theme:
  name: material
  language: es
  palette:
    primary: purple
  features:
    - navigation.tabs
    - navigation.sections
    - search.highlight
    - content.code.copy

nav:
  - Inicio: index.md
  - Primeros pasos:
    - Instalación: getting-started/installation.md
    - Quickstart: getting-started/quickstart.md
  - Guías:
    - Autenticación: guides/authentication.md
    - Despliegue: guides/deployment.md
  - API: api/overview.md

markdown_extensions:
  - admonition
  - pymdownx.highlight
  - pymdownx.superfences
  - pymdownx.tabbed
  - toc:
      permalink: true

Ventajas de Material for MkDocs:

• Búsqueda integrada sin servicios externos
• Modo oscuro
• Navegación por tabs
• Admonitions (bloques de aviso, nota, advertencia)
• Botón de copiar código con un clic
• Versionado de documentación
• Soporte de diagramas Mermaid

Docusaurus

Instalación:

npx create-docusaurus@latest my-docs classic

Estructura:

my-docs/
  docs/
    intro.md
    tutorial/
      step1.md
      step2.md
  blog/
    2026-01-01-first-post.md
  docusaurus.config.js
  sidebars.js

Ventajas de Docusaurus:

• Soporte de MDX (componentes React en Markdown)
• Blog integrado
• Internacionalización (i18n)
• Versionado de documentación
• Plugin de búsqueda con Algolia
• Temas personalizables

VitePress

VitePress es el generador de documentación del ecosistema Vue.js. Si ya usas Vue o simplemente quieres la máxima velocidad de compilación, VitePress es imbatible. Los cambios se reflejan en el navegador de forma prácticamente instantánea gracias a Vite.

Instalación:

npx vitepress init

Ventajas:

• Extremadamente rápido (basado en Vite)
• Hot Module Replacement instantáneo
• Componentes Vue en Markdown
• Tema por defecto muy limpio
• Configuración mínima

Docsify

Comparativa rápida

Escribir buena documentación

El framework Diataxis

Según el framework Diataxis, la documentación se divide en 4 tipos, y mezclarlos es el error más común:

1. Tutoriales: guían al usuario paso a paso. Orientados al aprendizaje. "Sigue estos pasos para desplegar tu primera app."
2. Guías prácticas: resuelven problemas concretos. Orientados a tareas. "Cómo configurar autenticación OAuth."
3. Explicaciones: dan contexto y entendimiento. Orientados a la comprensión. "Por qué usamos microservicios."
4. Referencia: describen la API, configuración, etc. Orientados a la información. "Parámetros del endpoint /users."

Estructura de una página

Cada página de documentación debe seguir una estructura predecible. El lector debe saber en los primeros 10 segundos qué va a aprender y qué necesita antes de empezar:

# Título claro y descriptivo

Párrafo introductorio que explica QUÉ se va a aprender
y POR QUÉ es importante. 1-2 frases.

## Prerrequisitos

- Conocimiento o herramienta necesaria
- Versión mínima requerida

## Paso 1: Nombre descriptivo del paso

Explicación breve de lo que se va a hacer.

```bash
comando a ejecutar

Explicación del resultado esperado.

Paso 2: Siguiente paso

...

Siguiente paso

Enlace a la página siguiente o recursos relacionados.

### Buenas prácticas

1. **Empieza por el resultado**: "Al final de esta guía tendrás X funcionando" es mejor que empezar con teoría.
2. **Código ejecutable**: todo bloque de código debe funcionar si se copia y pega.
3. **Explica el por qué**: no solo digas qué hacer, explica por qué.
4. **Actualiza regularmente**: documentación desactualizada es peor que no tener documentación.
5. **Usa admonitions**: bloques de nota, advertencia y peligro para información importante.
6. **Incluye ejemplos reales**: los ejemplos genéricos (`foo`, `bar`) son menos útiles que ejemplos del dominio.
7. **Revisa con usuarios**: pide a alguien que siga tu documentación sin ayuda. Si se atasca, la documentación tiene un hueco.
8. **Documenta mientras desarrollas**: no dejes la documentación para el final, porque nunca la escribirás.
9. **Incluye diagramas**: usa <a href="/sintaxis-avanzada/diagramas-mermaid" title="Diagramas Mermaid en Markdown">Mermaid</a> para diagramas integrados directamente en Markdown.
10. **Prueba los ejemplos**: verifica que los comandos y el código de ejemplo funcionan antes de publicar.

## Automatizar la documentación

### Deploy automático con GitHub Actions

Una de las grandes ventajas de documentar con Markdown es que puedes automatizar la publicación. Con este workflow de GitHub Actions, cada vez que hagas push a la rama `main` y los cambios afecten a archivos en `docs/`, el sitio se reconstruye y se publica automáticamente en GitHub Pages:

```yaml
name: Deploy Docs
on:
  push:
    branches: [main]
    paths: ['docs/**']

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install mkdocs-material
      - run: mkdocs build
      - uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./site

Verificar enlaces rotos

Los enlaces rotos son el mayor enemigo de la documentación. Añade este paso a tu CI para que cada pull request los detecte automáticamente:

- name: Check links
  uses: gaurav-nelson/github-action-markdown-link-check@v1
  with:
    folder-path: './docs'

Generar referencia de API automáticamente

Herramientas como TypeDoc (TypeScript), Sphinx (Python) y Javadoc (Java) generan documentación de referencia a partir de los comentarios en el código. Esto garantiza que la referencia siempre esté sincronizada con la implementación.

Ejemplos de documentación bien hecha

Estas documentaciones son referencia en la industria. Estúdialas para entender qué hace que la documentación funcione:

• Stripe: el estándar de oro en documentación de APIs. Ejemplos en múltiples lenguajes, respuestas interactivas, guías paso a paso.
• Tailwind CSS: documentación limpia, búsqueda excelente, ejemplos visuales.
• Next.js: estructura clara, tutoriales progresivos, API reference detallada.
• Rust: "The Rust Book" es un ejemplo de documentación tipo tutorial que lleva al lector de cero a competente.
• Django: divide claramente tutoriales, guías, referencia y explicaciones siguiendo el framework Diataxis.

Todas usan Markdown o un formato derivado como base.