A discussão "devo usar o wiki ou uma pasta docs no GitHub?" ressurge a cada poucos meses. Seguindo a regra de três strikes de Shawn Wang, o autor argumenta que usar o wiki no GitHub é um anti-padrão. O único benefício do wiki é sua disponibilidade constante, mas ele carece de versionamento, acesso local, revisão por pares e opções de branding.

Em contraste, uma pasta /docs integra a documentação com o código, suporta versionamento, habilita revisões de pull request e funciona com ferramentas como Vale e corretor ortográfico. As imagens devem ser hospedadas em outro lugar, pois o wiki não suporta uploads. Para publicar docs, use uma pasta /docs com GitHub Pages e um tema como just-the-docs.

Evite a branch gh-pages para manter os docs versionados com o código. À medida que os projetos crescem, os docs podem mover para um repo separado, mas os contribuidores já estarão acostumados ao fluxo de trabalho. O autor convida feedback no Twitter.