Posted on 2024-08-19
I like GitHub wikis as a simple way of writing documentation for a project. They use simple markup, they have pretty unobtrusive design, and they're easily accessible from a project repository. I use one at work to document our workflows and style guides. However, in my personal life I prefer to use Sourcehut, so I dedided to check out how Sourcehut wikis differ. After setting one up for a project, I find myself completely baffled as to why GitHub wikis work the way they do.
The main issue is that GitHub wikis are completely separate repositories. When you create a GH wiki, it creates a brand new <project_name>.wiki repository that you need to pull to your machine and work on separately. With Sourcehut, you need only create a wiki project and link it to your source repo, then write an index.md file. As long as this file is present, you can write any others and link them together as expected. This is much more logical to me; you manage your documentation in the same repository as your code, and anyone who prefers to read the documentation while they browse the code can do so however they choose.
I don't know what the decision-making behind the GitHub wiki setup was, but I really feel like they missed the mark on this. Not to mention that Sourcehut's interface is about 100x lighter and more responsive (and better designed, imho) than GitHub's. I feel like they could definitely trim the fat of the wiki interface without losing too much.