HN
login
The GitHub wiki is an anti-pattern (2022)michaelheap.com

Using the wiki on GitHub makes life more difficult for your users, and you as a maintainer. Use the `/docs` folder and GitHub Pages instead and keep your docs in sync with code

175 points•ibobev•8 days ago•111 comments•
#github#wiki#anti#pattern#anti pattern#github wiki#docs#life

111 comments

gwking7 days ago
The last paragraph says: > At some point your docs will outgrow a single folder, and then all bets are off. You’ll want a separate repo with its own build process...

My question is, why is this taken as a given? Is it so hard to have docs and code live together in version control after a certain scale? If so, what is the specific problem and what is the cause?

I ask because I've never been that satisfied with the various ways I've tried to organize projects in git. Recently I've been trying to keep the source, tests and docs together in the same tree so that changes are more localized. It seems to be helping me keep track of things, especially with coding agents so eager to make changes all over the place. I find their proclivity to repeat the same idea in multiple locations (agent instructions, docs, docstrings, help strings, comments) especially problematic.

bluGill7 days ago
On a large project you will have problems. You can maintain a monorepo anyway as many people do, and deal with the problems of a large monorepo. Or you can go to multirepo and deal with the issues of multirepo. Both have been done successfully, and both have significant problems that you need to work with.

Most people advocating a monorepo have never worked on a project large enough to see the issues with a monorepo and so are arguing for a monorepo without understanding the problems with them. For most people a monorepo is the correct answer because their project is small.

dualvariable7 days ago
Seems like if you're small enough, a monorepo is the right way to go because it doesn't matter at that scale, and if you're big enough, you'll have the resources to throw at making monorepos scale.
cortesoft7 days ago
> Most people advocating a monorepo have never worked on a project large enough to see the issues with a monorepo

Really? I feel like most of the stuff I have read advocating monorepos are from people at Google, which is a HUGE monorepo.

johannes12343217 days ago
> Is it so hard to have docs and code live together in version control

Managers and others won't touch the repo. (Sometimes it's better the don't...)

ragall7 days ago
We had managers and even non-engineers check-in documentation at Google: each page had an "Edit me" button that spawned an editor in a new tab with a CL(PR) ready. It worked very well.
giancarlostoro7 days ago
> I find their proclivity to repeat the same idea in multiple locations (agent instructions, docs, docstrings, help strings, comments) especially problematic.

I have not taken full advantage yet, but every source sub-directory can have its own CLAUDE.md or AGENTS.md file, with instructions for a given directory, whenever something like Claude opens a file in a folder, if there's an appropriate agent doc in the housing folder, it should read / apply its contents when working. Not sure how this happens with Sub-Agents on that note.

I think if you want both, you might as well add a ./docs/ directory, and put your md documents in there however you want, this has the upside of letting you have docs with your code always, as well as letting you link to direct source code files.

darau17 days ago
Weirdo checking in

I always initialize my projects with a src, and docs, directory, for exactly this reason.

My reasoning is that I shouldn't have to go hunting for the docs for the code, or vice versa.

guipsp7 days ago
Do you have only those two dirs at the top level? If so how are you finding it? I tend to have a docs dir at the top level, along with other build stuff
TheRoque7 days ago
I also put everything in one repo nowadays, no matter the usage, the language etc. All is synced, and all is accessible by my LLM. There are a lot of tools to manage monorepos, and frankly most of the time you don't even need them.
ffsm87 days ago
It makes releasing software a lot more complicated.

Not a big deal if you're basically the only developer and handroll the process - but poly repositories make release and dependency management a lot more straightforward to wrangle

bluGill7 days ago
Most of the time your repo is so small that you won't run into the problems of a large repo and so you don't need those tools. Don't confuse that for monorepos have no problems when they get large.
chungy7 days ago
Fossil (https://fossil-scm.org/home/doc/trunk/www/index.wiki) solves this pretty nicely. You can have documentation as files or in a special wiki namespace and it's versioned both ways, and every repository clone gets everything. Even better than that, your in-tree documentation files are rendered and browseable in exactly the same way as the dedicated wiki namespace.

The linked URL to the home page there can even serve as an example: the "trunk" is a check-in name (https://fossil-scm.org/home/doc/trunk/www/checkin_names.wiki) that points to the newest check-in on the "trunk" branch. You can replace it with any other reference to get the old version; eg, version-2.20 would work to get the version 2.20 of the docs, 2015-03-14 would work to get the version from 14 March 2015, etc.

YPCrumble7 days ago
Why is this easier or more effective than just a /docs directory?
chungy7 days ago
You absolutely can use "just a /docs" directory in Fossil. You can even point the web server to /doc/trunk/docs/index.md or whatever other file names you want. :-)
gatlin7 days ago
Parent comment linked to that answer.
mghackerlady7 days ago
Fossil is the best. Sqlite uses it
bigfishrunning7 days ago
Fossil was written for Sqlite in the same way that git was written for Linux. It's really a shame that more projects don't use it. I think that a github competitor (with social features, PRs, CI, etc) with a fossil backend would be very popular.
rpdillon7 days ago
Yep, I use Fossil for all my side projects. Super easy to host, tiny, includes everything I need for a project, all in one file. Great piece of software.
mikeocool7 days ago
In my experience, the docs for something like setting up a dev env are typically greatly improved by the second person who sets up the dev env, not the personal who originally wrote the docs.

In that case, when the docs are not associated with a code change, you want to make getting those improvements into the docs as frictionless as possible, otherwise the changes aren't going to get made.

Personally, I've found that making docs updates incredibly fast + easy to be far more valuable than anything you get from forcing doc changes through the full SDLC process. If someone has feedback on your docs changes they would have shared in a review, they can just update the docs instead.

yunwal7 days ago
> In my experience, the docs for something like setting up a dev env are typically greatly improved by the second person who sets up the dev env, not the personal who originally wrote the docs.

In my experience, this is also true of a lot of code as well. Your dev scripts should probably have much more relaxed standards than your service source or CI/CD. Ideally I could define merge requirements by directory without doing some weird shenanigans with the CODEOWNERS file and a bot.

juancn7 days ago
That could be easily be corrected by relaxing merge gates for changes only to the `docs` folder (or some suitable naming pattern).

You can even do live edits on the web if you don't want to use a command line.

wavemode7 days ago
You can set up automation and/or configuration such that changes to the docs folder don't require code review.
jameshart7 days ago
Corrections and improvements to docs are just a bugfix though?
codazoda7 days ago
I'm no fan of GitHub add-ons and I agree with the premise here but...

I can think of one other possibility. It's easier to write in a wiki via the browser. I can open that on my phone and edit docs. I can open it in my browser and edit docs.

On desktop it's a tiny bit more to pull the repo and open it in your editor (and you might already be there) but that tiny bit can be enough to stop you from writing documentation. For me, writing documentation must be totally painless so that I'll actually do it.

Why am I not a fan of the add-ons like PR's, wiki's, discussions, projects, and issues? Because they each introduce vendor lock-in to varying degrees.

sheept7 days ago
Wikis don’t have as much vendor lock-in as other Github features since they’re just git repos,[0] so you can clone and push the wiki elsewhere.

[0]: https://docs.github.com/en/communities/documenting-your-proj...

wky7 days ago
GitHub is pretty good about editing on the web. Markdown files can be edited straight from github.com. On desktop you can hit the period key to directly open the repo in vscode.dev. Technically on mobile you can change github.com to github.dev to do the same, though the editing experience is worse than directly editing on GitHub.
cocoto7 days ago
You can edit single files in most git forges and it will open a pull request for you, the workflow is not that bad.
stephenlf7 days ago
I agree with this post. I’ve never found the GitHub wiki experience to be particularly ergonomic. I don’t have any issues with it, but it’s no more convenient than a simple /docs folder. And from there, it’s almost trivial to turn /docs into GitHub pages. Similar effort for a much better end product.

Wikis typically connote distributed, anonymous edits. This feature is partially covered by git already.

cxr7 days ago
> I’ve never found the GitHub wiki experience to be particularly ergonomic.

That's because the original sin of GitHub "wikis" is that they weren't (and most of them still aren't) even wikis. There's this perverse thing that happened during the wiki age, where people unable or unwilling to get on board decided to just start calling things "wikis" even though they exemplify the very thing that the wiki was invented as a response to. The reckless debasing of the word then infected adjacent spaces. Sourcehut's "read-only wikis" (wat) aren't even designed to be edited in the browser; on Sourcehut, "Publishing your changes is as easy as committing them and pushing them upstream." Newsflash: That's not a wiki.

masklinn7 days ago
Yeah you can configure gh “wikis” to be freely editable but that’s not the default and most of them are not,

Read the full thread on Hacker News →

Related stories