Un desarrollador ha planteado el argumento de que el wiki de GitHub es una mala idea, y el argumento se basa en una única ventaja declarada: el wiki siempre está ahí. El resto del argumento es una larga lista de quejas, la mayoría de las cuales se reducen a que el wiki es un wiki.
La publicación, titulada «El wiki de GitHub es un antipatrón», traza una línea sencilla. Utilice el wiki si desea una página a la que cualquier persona pueda acceder desde cualquier lugar de su repositorio con un solo clic. Utilice una carpeta de documentación si desea documentación que viaje con su código, se revise como el código y se mantenga local cuando alguien clone su proyecto.
Una Ventaja Declarada
El autor comienza con una concesión: hay un beneficio al usar un wiki. Puede acceder al contenido del wiki con un solo clic desde cualquier lugar del repositorio. Esa es la totalidad del argumento para la existencia del wiki.
La publicación luego enumera varias razones en contra del wiki, incluido la ausencia de versionado. La documentación no se versiona junto con su código cuando usa el wiki, lo que significa que las versiones anteriores de la documentación son difíciles de encontrar. Esa es otra razón en contra del wiki, aunque se enmarque como una desventaja en lugar de un beneficio.
Por Qué Importa el Versionado
El argumento más sólido en contra del wiki también es el más sencillo. La documentación almacenada en una carpeta /docs se mueve con su código. Si necesita usar una versión anterior del software, la documentación es fácil de encontrar junto con él.
La publicación también señala que las ediciones de la documentación reciben el mismo trato que el código cuando residen en la carpeta /docs. Pasan por el proceso de solicitud de extracción, lo que significa que reciben una revisión completa entre pares. Esa es una diferencia real del wiki, donde no existe un proceso de revisión.
GitHub Actions puede analizar la documentación en una carpeta /docs utilizando herramientas como Vale. Las personas pueden trabajar con herramientas familiares como vscode con corrector ortográfico. La carpeta /docs también admite imágenes y marcas personalizadas, aunque la publicación no lo dice directamente.
Mover la Documentación Fuera del Wiki
La publicación ofrece un camino claro para cualquier persona que desee alejarse del wiki. Agregue su documentación a su repositorio en la carpeta /docs. No use la rama gh-pages, porque eso impide que la documentación se versione junto con el código.
) Configure un proceso de compilación de GitHub Pages para publicar la documentación. Si está recién comenzando, el autor recomienda usar el tema just-the-docs y permitir que GitHub compile y publique su documentación automáticamente. Si prefiere crear su propio flujo de trabajo, puede usar una Acción de GitHub para publicar la documentación.
) El paso final es sencillo. Agregue una sola página de wiki que dirija a las personas a la documentación alojada. De esta manera, cualquier persona que haga clic en el enlace de la wiki verá una nota que los dirige a la documentación real.
) El punto donde falla
) En algún momento, la documentación superará una sola carpeta. Entonces, todo está en juego. Querrá un repositorio separado con su propio proceso de compilación, pautas de revisión de solicitudes de extracción y toda una serie de otras cosas.
) La publicación argumenta que en ese punto, las personas ya están acostumbradas a trabajar con documentación en un repositorio. La migración de /docs a su propio repositorio debería ser fluida para los colaboradores.
) El argumento del patrón antisistémico
) El autor considera el uso de la wiki en GitHub como un patrón antisistémico. La publicación hace este caso enumerando muchas más razones para no usar la wiki que razones para usarla.
) La wiki no supera esa prueba porque sus beneficios son pocos y sus inconvenientes se acumulan. El acceso con un solo clic es real, pero es superado por todo lo demás. La falta de versionado, la revisión par ausente, la marca limitada: estos no son inconvenientes menores. Se suman a un sistema que es más difícil de mantener y menos útil que la alternativa.
) La publicación concluye invitando a los lectores a compartir sus pensamientos en Twitter.
) Hechos clave de la publicación
- ) Título: «La wiki de GitHub es un patrón antisistémico»
- ) Plataforma: GitHub
- Disparador de discusión: regla de tres intentos
- Afirmación clave: usar la wiki es un antipatrón
La publicación es una especie de honestidad divertida. El autor construye todo un argumento alrededor de dos ventajas reales —una real, una implícita— y una lista de quejas que en gran medida se reducen a que la wiki es una wiki. Eso es divertido y honesto a la vez.
El argumento es convincente porque es específico. Compara la wiki con una carpeta /docs lado a lado, y las diferencias son marcadas. La revisión de solicitudes de extracción, el linting, la disponibilidad local — estos son beneficios prácticos que la wiki simplemente no ofrece.
La ruta de migración también merece ser mencionada. El autor trata el cambio de la wiki a /docs como una progresión natural, no una interrupción. Ese es un marco útil para cualquiera que esté considerando el cambio.
La publicación es un recordatorio de que la mejor herramienta no siempre es la que viene incluida con la plataforma. A veces, la opción integrada es la que estorba. En este caso, la wiki es el problema, no la solución.
La regla de tres intentos del autor significa que este argumento ha estado hirviendo a fuego lento durante un tiempo. Ahora está escrito, y la conversación se ha trasladado a Twitter. La carpeta /docs vive.
Material fuente: “The GitHub wiki is an anti-pattern (2022),” michaelheap.com.
Recibe El Cuaderno.
Las mejores historias del día y cada veredicto nuevo, en español claro, en tu correo a las siete. Un correo al día, nada más.