De auteur stelt dat het gebruik van de GitHub-wiki een 'anti-pattern' is. Hoewel een wiki snel toegankelijk is, biedt een /docs-map aanzienlijk meer voordelen:
- Versiebeheer en Review: Documentatie wordt samen met de code geversioneerd en kan via pull requests worden gereviewd.
- Tooling: Ontwikkelaars kunnen hun eigen bekende tools (zoals VS Code) gebruiken en automatisering (zoals linting via GitHub Actions) implementeren.
- Toegankelijkheid: Documentatie is lokaal beschikbaar na het clonen van de repository.
De aanbevolen aanpak is om documentatie in de /docs-map te plaatsen en deze te publiceren via GitHub Pages (met bijvoorbeeld just-the-docs of Hugo), terwijl een enkele wikipagina enkel dient als doorverwijzing. Deze methode schaalt bovendien beter naar een aparte repository zodra de documentatie te groot wordt.
De GitHub-wiki is een anti-pattern
De eerste versie van dit artikel begon met de zin: "Je kunt de wiki of een /docs-map gebruiken voor je GitHub-project, beide zijn valide keuzes." Terwijl ik verder schreef, realiseerde ik me echter dat er slechts één reden is om een wiki te gebruiken, en vele redenen om dat niet te doen. Sterker nog, ik beschouw het gebruik van de wiki op GitHub als een anti-pattern.
De voordelen van het gebruik van een wiki
- Je hebt vanuit elk deel van de repository met één klik toegang tot de inhoud van de wiki.
Dat is het. Echt, het enige voordeel dat ik heb kunnen vinden bij het gebruik van de wiki is dat deze altijd direct beschikbaar is.
De redenen om de wiki niet te gebruiken
Daartegenover staan de voordelen van een /docs-map:
- Versiebeheer: Documentatie wordt samen met je code geversioneerd. Als je een oude versie van de code moet gebruiken, zijn de bijbehorende documenten eenvoudig te vinden.
- Lokale beschikbaarheid: Documentatie in een wiki is niet lokaal beschikbaar wanneer iemand je repository clonet (je kunt de wiki wel apart clonen, maar dit is een verborgen functie).
- Peer review: Wijzigingen in de documentatie krijgen dezelfde behandeling als code; ze doorlopen een volledig peer review-proces via pull requests.
- Automatisering: Je kunt GitHub Actions gebruiken om je documentatie te linten met tools zoals Vale.
- Bekende tooling: Mensen kunnen werken met tools die ze al kennen (bijvoorbeeld VS Code met spellingscontrole).
- Branding: Wiki's bieden beperkte mogelijkheden voor branding; ze zien er allemaal vrijwel hetzelfde uit.
- Afbeeldingen: De wiki ondersteunt geen uploads van afbeeldingen, waardoor je afbeeldingen sowieso ergens anders moet hosten.
Documentatie effectief implementeren
Nu je overtuigd bent van het idee om documentatie naast je code te houden, is de vraag hoe je dit voor anderen toegankelijk maakt.
- Voeg je documentatie toe in de
/docs-map. Gebruik hiervoor niet de gh-pages branch, omdat dit voorkomt dat de documentatie samen met de code wordt geversioneerd.
- Stel een GitHub Pages build in om de documentatie te publiceren.
- Voor beginners raad ik het
just-the-docs thema aan, waarbij GitHub het bouwen en publiceren van je documentatie regelt.
- Als je liever je eigen workflow bouwt (bijvoorbeeld met Hugo), kun je een specifieke GitHub Action gebruiken om de documentatie te publiceren.
- Voeg één enkele wikipagina toe die gebruikers doorverwijst naar de gepubliceerde documentatie.
Het gebruik van de /docs-map is de optie met de gunstigste verhouding tussen inspanning en resultaat terwijl je aan een nieuw product bouwt. Op een gegeven moment zal je documentatie echter te groot worden voor een enkele map. Op dat punt is alles mogelijk: je zult waarschijnlijk een aparte repository willen met een eigen build-proces, richtlijnen voor pull request reviews en diverse andere zaken. Omdat mensen op dat moment al gewend zijn om met documentatie in een repository te werken, zou de migratie van /docs naar een eigen repository naadloos moeten verlopen voor je contributors.
De GitHub-wiki is een anti-pattern
De eerste versie van dit artikel begon met de zin: "Je kunt de wiki of een /docs-map gebruiken voor je GitHub-project, beide zijn valide keuzes." Terwijl ik verder schreef, realiseerde ik me echter dat er slechts één reden is om een wiki te gebruiken, en vele redenen om dat niet te doen. Sterker nog, ik beschouw het gebruik van de wiki op GitHub als een anti-pattern.
De voordelen van het gebruik van een wiki
- Je hebt vanuit elk deel van de repository met één klik toegang tot de inhoud van de wiki.
Dat is het. Echt, het enige voordeel dat ik heb kunnen vinden bij het gebruik van de wiki is dat deze altijd direct beschikbaar is.
De redenen om de wiki niet te gebruiken
Daartegenover staan de voordelen van een /docs-map:
- Versiebeheer: Documentatie wordt samen met je code geversioneerd. Als je een oude versie van de code moet gebruiken, zijn de bijbehorende documenten eenvoudig te vinden.
- Lokale beschikbaarheid: Documentatie in een wiki is niet lokaal beschikbaar wanneer iemand je repository clonet (je kunt de wiki wel apart clonen, maar dit is een verborgen functie).
- Peer review: Wijzigingen in de documentatie krijgen dezelfde behandeling als code; ze doorlopen een volledig peer review-proces via pull requests.
- Automatisering: Je kunt GitHub Actions gebruiken om je documentatie te linten met tools zoals Vale.
- Bekende tooling: Mensen kunnen werken met tools die ze al kennen (bijvoorbeeld VS Code met spellingscontrole).
- Branding: Wiki's bieden beperkte mogelijkheden voor branding; ze zien er allemaal vrijwel hetzelfde uit.
- Afbeeldingen: De wiki ondersteunt geen uploads van afbeeldingen, waardoor je afbeeldingen sowieso ergens anders moet hosten.
Documentatie effectief implementeren
Nu je overtuigd bent van het idee om documentatie naast je code te houden, is de vraag hoe je dit voor anderen toegankelijk maakt.
- Voeg je documentatie toe in de
/docs-map. Gebruik hiervoor niet de gh-pages branch, omdat dit voorkomt dat de documentatie samen met de code wordt geversioneerd.
- Stel een GitHub Pages build in om de documentatie te publiceren.
- Voor beginners raad ik het
just-the-docs thema aan, waarbij GitHub het bouwen en publiceren van je documentatie regelt.
- Als je liever je eigen workflow bouwt (bijvoorbeeld met Hugo), kun je een specifieke GitHub Action gebruiken om de documentatie te publiceren.
- Voeg één enkele wikipagina toe die gebruikers doorverwijst naar de gepubliceerde documentatie.
Het gebruik van de /docs-map is de optie met de gunstigste verhouding tussen inspanning en resultaat terwijl je aan een nieuw product bouwt. Op een gegeven moment zal je documentatie echter te groot worden voor een enkele map. Op dat punt is alles mogelijk: je zult waarschijnlijk een aparte repository willen met een eigen build-proces, richtlijnen voor pull request reviews en diverse andere zaken. Omdat mensen op dat moment al gewend zijn om met documentatie in een repository te werken, zou de migratie van /docs naar een eigen repository naadloos moeten verlopen voor je contributors.
Groetjes,