El wiki de GitHub es un anti-patrón: mejor una carpeta /docs en el repositorio

Michael Heap lo tiene claro: el wiki de GitHub es un anti-patrón. Después de darle vueltas al debate recurrente —wiki o carpeta de documentación dentro del repo—, concluye que solo hay una razón para usar el wiki y demasiadas para no hacerlo. Su recomendación por defecto: meter la documentación en /docs y publicarla con GitHub Pages.

Heap reconoce que la discusión vuelve cada seis meses, y que esta vez se decidió a escribirla siguiendo la regla de las tres strikes de Shawn Wang. Lo llamativo es cómo cambió el texto mientras lo redactaba: arrancó con un "ambas opciones son válidas" y acabó convencido de que solo existe un motivo a favor del wiki.

Un solo punto a favor, y es flojo

El único beneficio que encuentra es de acceso: el wiki está a un clic desde cualquier parte del repositorio. No hay un segundo. Ni búsqueda, ni integración, ni nada. Solo que siempre está ahí.

Frente a eso, el resto. La documentación del wiki no se versiona junto al código, así que consultar una versión antigua se convierte en un ejercicio de arqueología; con /docs cada versión del repositorio arrastra las suyas. Al clonar el proyecto no te llevas la documentación: se puede clonar el wiki por separado, pero es una función escondida que casi nadie conoce. Las ediciones no pasan por pull request, de modo que no hay revisión por pares ni historial con el mismo tratamiento que el código. Tampoco puedes lintar la prosa: con /docs, un flujo de trabajo sobre el repositorio permite pasar herramientas como Vale en cada cambio. Y quien escribe pierde su editor de siempre, con corrector y plugins.

A eso se suman dos detalles más pequeños pero molestos: el aspecto es uniforme y con poca capacidad de personalización, y el wiki no admite subida de imágenes, así que al final acabas alojándolas en otro sitio de todos modos.

Cómo montarlo

La propuesta es sencilla. La carpeta /docs en el repositorio, nada de la rama gh-pages, porque esa impide versionar la documentación junto al código. Encima, una build de GitHub Pages que publique el contenido. Para empezar, el tema just-the-docs y dejar que GitHub compile y sirva. Si prefieres un flujo propio, por ejemplo con Hugo, existe una action ya hecha para publicar. Y luego una única página de wiki que apunte a la documentación publicada, para no romper enlaces antiguos.

Ese último detalle da sentido a todo: no se trata de prohibir el wiki, sino de usarlo como cartel que redirige, no como almacén de contenido.

Cuando el proyecto crece, la carpeta se queda corta y toca un repositorio aparte, con su propio proceso de build y sus normas de revisión. Heap señala que la migración entonces es indolora, porque el equipo ya viene de trabajar con documentación dentro de un repositorio.

Merece la pena aunque solo sea por el efecto acumulativo. Un wiki que nadie revisa, que no se versiona y donde los cambios no se discuten acaba desincronizado del código que pretende explicar. La carpeta cuesta lo mismo de mantener y hereda todo el flujo de trabajo que el equipo ya tiene montado para el código.