The “should I use the wiki or a docs directory on GitHub?” conversation comes up all 6 months or so, and following Shawn Wang’s three strikes rule I idea it was concerning period I wrote item downward concerning it.
The first type of this article opened alongside “You can use the wiki or a docs directory for your GitHub project, the two are valid choices” but as I wrote more, I realised that there is a sole logic to use a wiki, and many additional reasons not to use the wiki. So many in fact, that I regard using the wiki on GitHub is an anti-pattern.
Let’s commencement alongside the benefits of using a wiki:
- You can get to the wiki contents in a sole click from anyplace in the repo
- There is no 2.
Really, the lone advantage that I’ve been capable to discover to using the wiki is that it’s continually there.
How concerning the reasons not to use the wiki?
- Documentation is versioned alongside your code whenever using the /docs folder. If you need to use an old version, the docs are uncomplicated to find
- The records isn’t accessible locally whenever person clones your repo (you can copy the wiki separately, but this is a hidden feature)
- Documentation edits get the identical care as code. They get a complete equal assessment through the drag petition process
- You can use GitHub Actions to lint your docs using tools specified as Vale
- People can activity alongside tooling that they already cognize (e.g. vscode alongside spellcheck)
- Wikis provision constricted branding opportunities. They all appearance beautiful much the same
- The wiki doesn’t assistance depiction uploads, so you have to put images location alternatively anyway
Now that you’re sold on the idea of keeping docs alongside your code, how do you create it uncomplicated for group to perspective them?
- Add your docs to your repository in the /docs folder. Do not use the gh-pages branch as this prevents docs being versioned alongside code
- Set up a GitHub pages build to publish the docs
- If you’re fair getting started, I propose using the just-the-docs theme and letting GitHub build and publish your docs
- If you favor to build your own workflow (e.g. using Hugo), you can use this GitHub Action to publish the docs
- Add a sole wiki leaf directing group to the hosted documentation
Using the /docs directory is the highest effort-to-reward proportion choice whilst you’re construction out a new product. At several item your docs volition outgrow a sole folder, and afterward all bets are off. You’ll desire a distinct repo alongside its own build process, drag petition assessment guidelines and a entire presenter of another things. At that item group are already used to operating alongside docs in a repository, and the immigration from /docs to its own repo have to be seamless for your contributors.
Whether you concur or disagree, I’d affection to comprehend your thoughts on Twitter
