⏱️ Lectura: 10 min
Michael Heap encontró una sola razón real para usar la wiki de GitHub en vez de una carpeta /docs dentro del propio repositorio: siempre está a un clic de distancia. Todo lo demás juega en contra, según detalla en su artículo publicado en michaelheap.com.
📑 En este artículo
La discusión sobre dónde guardar la documentación de un proyecto en GitHub reaparece cada seis meses en foros y redes de desarrolladores, y Heap decidió zanjarla por escrito tras acumular esa cantidad de repeticiones. Su conclusión: la wiki de GitHub es un antipatrón para cualquier equipo que ya usa pull requests para revisar código.
TL;DR
- La wiki de GitHub tiene una sola ventaja real: está a un clic desde cualquier parte del repositorio.
- Guardar los documentos en una carpeta /docs los versiona junto al código: cada commit fija qué documentación corresponde a esa versión.
- Los cambios en /docs pasan por pull request y revisión de pares; la wiki se edita sin ese control.
- GitHub Pages puede publicar el contenido de /docs automáticamente con un workflow de Actions.
- Subir imágenes no funciona en la wiki: hay que alojarlas en otro servicio de todas formas.
- El tema just-the-docs permite lanzar un sitio de documentación con Jekyll sin escribir HTML desde cero.
- Cuando /docs crece demasiado, migrar a un repositorio propio es el siguiente paso natural.
Qué pasó
El post de Heap parte de una premisa incómoda para quien defiende la wiki: al principio pensaba escribir algo neutral, del tipo «podés usar la wiki o una carpeta docs, las dos son válidas». Pero al listar los argumentos a favor de cada opción encontró un solo punto en la columna de la wiki (que siempre está disponible con un clic desde el repositorio) frente a media docena en la columna de /docs.
Esa asimetría es la que lo llevó a calificar el uso de la wiki como antipatrón: no porque la función esté mal diseñada, sino porque casi siempre existe una alternativa mejor para el mismo trabajo, con el mismo esfuerzo de configuración inicial.
Contexto e historia de la wiki de GitHub
La wiki de GitHub funciona, técnicamente, como un repositorio Git separado y paralelo al del proyecto: cada repositorio público (y varios privados) tiene automáticamente uno oculto con el sufijo .wiki.git. Se edita desde una interfaz web simplificada, sin pasar por pull request, lo que la hizo atractiva durante años para notas rápidas, runbooks internos o documentación colaborativa que no necesitaba revisión formal.
La alternativa que propone Heap no es nueva: usar una carpeta /docs (o /documentation) dentro del propio repositorio de código, y publicarla como sitio estático con GitHub Pages. Esta práctica se popularizó junto con generadores de sitios como Jekyll, y hoy conviven decenas de temas listos para usar, entre ellos just-the-docs, pensado específicamente para documentación técnica.
Wiki de GitHub vs. carpeta /docs: la comparación técnica
La diferencia de fondo entre ambas opciones es el control de versiones. Cuando la documentación vive en /docs, cada commit del repositorio principal fija qué versión de los documentos corresponde a esa versión del código: si alguien necesita ver cómo se configuraba una función en una versión anterior, alcanza con hacer checkout del tag correspondiente. La wiki, en cambio, es un historial único, sin relación directa con los tags o releases del proyecto.
| Aspecto | Wiki de GitHub | Carpeta /docs |
|---|---|---|
| Versionado junto al código | No: historial propio y separado | Sí: cada commit fija su versión |
| Disponible al clonar el repo | No por defecto (hay que clonarla aparte) | Sí, siempre |
| Revisión de cambios | Edición directa, sin pull request | Pull request con revisión de pares |
| Lint / CI sobre el contenido | No aplica | Sí, por ejemplo con Vale en GitHub Actions |
| Soporte de imágenes propias | No: hay que alojarlas en otro servicio | Sí, junto a los archivos del repo |
| Personalización visual | Muy limitada, todas se ven igual | Total, vía tema de Jekyll/Hugo o CSS propio |
El punto del linting merece un ejemplo concreto: con la documentación en /docs, un workflow de GitHub Actions puede correr Vale en cada pull request para detectar errores de estilo o términos prohibidos, algo imposible de automatizar sobre el contenido de una wiki porque no pasa por ningún pipeline de CI.
Cómo empezar
Migrar de la wiki a /docs no exige herramientas nuevas: alcanza con Git y, si querés publicar el resultado como sitio, una cuenta de GitHub con Pages habilitado.
Paso 1: crear la carpeta y el primer documento
mkdir docs
echo "# Documentacion del proyecto" > docs/index.md
git add docs
git commit -m "docs: mover documentacion a carpeta docs"
git push origin mainEste primer commit ya deja la documentación versionada junto al código: cualquiera que clone el repositorio la tiene disponible sin pasos extra.
Paso 2: instalar el CLI de GitHub para migrar contenido existente
Si ya tenías contenido en la wiki, podés clonarla como cualquier repositorio Git (es un .git más) y copiar los archivos Markdown a /docs. Para autenticarte y automatizar el proceso, instalá gh, el CLI oficial de GitHub:
# Windows (PowerShell, con winget)
winget install --id GitHub.cli
# macOS (con Homebrew)
brew install gh
# Linux (Debian/Ubuntu)
sudo apt install ghgh auth login
git clone https://github.com/usuario/repositorio.wiki.git wiki-temporal
cp wiki-temporal/*.md docs/
rm -rf wiki-temporalPaso 3: publicar con GitHub Pages
Desde Settings → Pages del repositorio, elegí la rama principal y la carpeta /docs como origen. GitHub arma el sitio con Jekyll automáticamente. Si preferís un generador distinto, un workflow de Actions puede compilar y publicar el resultado:
name: Publicar documentacion
on:
push:
branches: [main]
paths: ["docs/**"]
jobs:
deploy:
runs-on: ubuntu-latest
permissions:
pages: write
id-token: write
steps:
- uses: actions/checkout@v4
- uses: actions/configure-pages@v5
- uses: actions/jekyll-build-pages@v1
with:
source: ./docs
- uses: actions/deploy-pages@v4Con ese workflow, cada push que toque archivos dentro de docs/ dispara un build y una publicación automática. Es el mismo patrón que describe Heap para no depender de la rama gh-pages, que rompe el versionado porque separa la documentación publicada del historial de código.
Verificar que quedó activo
Para confirmar que Pages está sirviendo el sitio, entrá a Settings → Pages: la parte superior muestra «Your site is live at» seguido de la URL. También podés comprobarlo por línea de comandos:
curl -I https://usuario.github.io/repositorio/Una respuesta HTTP/2 200 confirma que el sitio está publicado y accesible.
💡 Tip: dejá una sola página en la wiki (o desactivala) que redirija al sitio publicado en /docs, así cualquiera que llegue por el acceso directo de la wiki encuentra el contenido real.
⚠️ Ojo: no uses la rama gh-pages para publicar: al vivir aparte del historial principal, rompe la relación entre cada versión del código y su documentación correspondiente.
Impacto y análisis
Para equipos y proyectos open source en América Latina, el argumento tiene un peso extra: gran parte de los mantenedores hispanohablantes ya usa pull requests como flujo único de trabajo, tanto para código como para traducciones. Meter la documentación en ese mismo flujo evita que un contribuidor nuevo tenga que aprender dos formas distintas de proponer cambios: una para el código y otra, sin revisión, para la wiki.
Hay una excepción honesta que Heap no ignora: en un equipo muy chico, sin proceso de revisión formal, la wiki sigue siendo la opción de menor fricción para notas internas rápidas que nadie necesita versionar. El costo de configurar /docs y Pages no se justifica si la documentación es efímera o solo la lee el propio equipo.
Qué sigue
La recomendación de Heap es clara mientras el proyecto es joven: usar /docs porque tiene la mejor relación esfuerzo/beneficio para empezar. El límite aparece cuando la documentación crece tanto que necesita su propio pipeline de build, sus propias reglas de revisión o un dominio propio. En ese punto, migrar a un repositorio dedicado es un paso natural, porque los contribuidores ya están acostumbrados a trabajar con documentación versionada dentro de un repo.
flowchart TD
A["Documentacion en carpeta /docs"] --> B{"Crece mucho?"}
B -- "No" --> C["Se mantiene en el mismo repo"]
B -- "Sí" --> D["Se migra a un repositorio propio"]
D --> E["Pipeline de build independiente"]
D --> F["Reglas propias de revision"]📖 Resumen en Telegram: Ver resumen
Probalo vos: creá hoy mismo la carpeta docs en tu repositorio y activá GitHub Pages desde Settings → Pages para ver el sitio publicado en minutos.
Preguntas frecuentes
¿La wiki de GitHub sigue sirviendo para algo?
Sí, para notas rápidas o documentación interna de un equipo muy chico que no necesita revisión formal ni versionado junto al código.
¿Qué pasa si mi documentación en /docs crece demasiado?
Se migra a un repositorio propio, con su propio pipeline de build y sus propias reglas de revisión, algo que Heap señala como el siguiente paso natural.
¿Necesito Jekyll para publicar la carpeta /docs?
No, GitHub Pages usa Jekyll por defecto si no configurás nada más, pero podés compilar con Hugo, MkDocs u otro generador y publicar el resultado con la Action oficial de Pages.
¿La wiki admite subir imágenes propias?
No directamente: hay que alojarlas en otro servicio y enlazarlas desde la página de la wiki.
¿Cómo migro el contenido que ya tengo en la wiki?
Clonando el repositorio oculto repositorio.wiki.git con Git y copiando los archivos Markdown a la carpeta /docs del repo principal.
¿Este enfoque sirve para documentación privada de una empresa?
Sí, funciona igual en repositorios privados, con el mismo control de acceso que ya tiene el repositorio de código.
Referencias
- The GitHub wiki is an anti-pattern: el artículo original de Michael Heap que plantea el argumento central de esta nota.
- GitHub Pages: documentación oficial para publicar sitios estáticos desde un repositorio, incluida la carpeta /docs.
- just-the-docs: tema de Jekyll pensado específicamente para sitios de documentación técnica.
- Vale: linter de prosa que puede correr en GitHub Actions sobre archivos Markdown.
- actions/deploy-pages: la GitHub Action oficial para publicar contenido estático en Pages.
📱 ¿Te gusta este contenido? Únete a nuestro canal de Telegram @programacion donde publicamos a diario lo más relevante de tecnología, IA y desarrollo. Resúmenes rápidos, contenido fresco todos los días.
Imagen destacada: Foto de Krishna Pandey en Unsplash
0 Comentarios