La wiki de GitHub es un antipatrón (2022)

Artículo original ↗ Discusión en Hacker News ↗

Muchos desarrolladores sostienen que la wiki integrada de GitHub es un «antipatrón» frente a mantener la documentación en un directorio `/docs` dentro del repositorio principal. Señalan que las wikis viven en un repositorio separado y oculto, sin flujos de revisión de código estándar, pueden desincronizarse del código, son más difíciles de usar para automatización y motores de búsqueda, y a menudo ni siquiera son wikis «reales» porque normalmente se desactiva la edición pública. Otros señalan que las wikis reducen la barrera para ediciones rápidas desde el navegador y notas tipo bloc de notas, pero la opinión predominante favorece la documentación dentro del repositorio, a veces generada en sitios de documentación completos, especialmente a medida que los proyectos crecen.

Postura general sobre la wiki de GitHub frente a /docs

  • Muchos coinciden en que la wiki de GitHub es un «antipatrón» en comparación con un directorio /docs.
  • Principales críticas: UX torpe, repositorio aparte oculto sin herramientas normales, propiedades débiles de «wiki real» (no editable públicamente por defecto, estructura limitada como la ausencia de directorios).
  • Otros ven valor en las ediciones de baja fricción basadas en navegador, los blocs de notas improvisados y las wikis comunitarias separadas de la documentación de desarrollo.

Ergonomía y flujo de trabajo

  • Se considera que /docs requiere un esfuerzo aproximadamente equivalente, pero se integra mejor con:
    • Revisiones de código y flujos de trabajo de PR.
    • GitHub Pages y generadores de sitios estáticos (Sphinx, etc.).
    • Clones locales y acceso sin conexión.
  • Algunos destacan comodidades de la wiki:
    • Acceso con un clic y navegación en la barra lateral.
    • No hace falta configurar nada; «simplemente está ahí».
    • Es más fácil para colaboradores no técnicos que no quieren lidiar con git, PR y CI.

Versionado y acoplamiento con el código

  • Hay un fuerte apoyo a mantener la documentación en el mismo repositorio para que el código y la documentación puedan actualizarse de forma atómica.
  • Un repositorio wiki separado implica:
    • No hay acoplamiento automático de las versiones de la documentación con las versiones del código.
    • Las ediciones pueden «pudrirse» sin que nadie lo note, ya que evitan los PR.
  • Contraargumento: la wiki sigue siendo un repositorio git, así que el versionado existe; el acoplamiento puede gestionarse con etiquetas, submódulos o automatización (por ejemplo, sincronizar /docs → wiki con GitHub Actions, o hacer que la wiki sea un submódulo).

Fricción, revisiones y contribución

  • Un sector: la documentación debería pasar por el mismo proceso de revisión que el código para garantizar corrección y visibilidad.
  • Sector opuesto: los requisitos de revisión/CI para cambios triviales en la documentación generan tanta fricción que la documentación nunca se actualiza.
  • Mitigaciones sugeridas:
    • Relajar las puertas de merge o la CI para cambios solo de Markdown.
    • Tratar «las actualizaciones solo de documentación pueden omitir revisión/CI» como una regla de proceso en lugar de una herramienta impuesta.
    • Usar ediciones de un solo archivo basadas en la web y PR abiertos automáticamente para reducir la fricción.

Búsqueda, indexación e IA/agentes

  • Preocupación de que las wikis de GitHub estén menos indexadas o sujetas a restricciones (por ejemplo, recuentos de estrellas, no editabilidad pública), lo que dificulta que se descubran mediante búsqueda o IA.
  • La documentación en /docs se considera más visiblemente accesible para la búsqueda y más fácil para que los agentes la correlacionen con cambios en el código.

Herramientas alternativas y estructura del repositorio

  • Se cita Fossil como ejemplo de un sistema donde la wiki y la documentación en el árbol son elementos de primera clase, unificados y bien versionados.
  • Algunos inicializan siempre los proyectos con src/ y docs/ en la raíz para mantener el código y la documentación juntos.
  • Hay una discusión paralela sobre monorepo frente a multirrepo: el consenso es que ambos tienen serios compromisos de escalabilidad; para proyectos pequeños, un único repositorio (con la documentación incluida) suele ser lo más simple.