Yet another Hacker News

36 points ibobev 1 hour ago 24 comments

stephenlf 54 minutes ago | parent

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.

cxr 14 minutes ago | parent

> 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.

hn1rig3rak 40 minutes ago | parent

Biggest thing for me is wiki edits skip code review, so docs rot silently while a /docs PR at least shows up in the diff next to the change.

freedomben 33 minutes ago | parent

Indeed, and also now with agents everywhere the docs can be updated and checked more regularly. If it's in the wiki, you can clone it locally and put an AGENTS.md line informing of where the docs are, but it's still a separate repo to deal with. Credit where due, it was a revolution (even a godsend) in it's time, but at this point I agree a /docs is better.

nchmy 20 minutes ago | parent

im having trouble connecting the dots here. How does adding the friction of code review reduce rot?

anon48293 11 minutes ago | parent

You can spot a code change without a docs change or vice versa

chungy 34 minutes ago | parent

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.

YPCrumble 16 minutes ago | parent

Why is this easier or more effective than just a /docs directory?

gatlin 12 minutes ago | parent

Parent comment linked to that answer.

mghackerlady 13 minutes ago | parent

Fossil is the best. Sqlite uses it

bocklund 33 minutes ago | parent

Interesting because I just added a wiki for one of my projects. I'm not using it for docs, since the project already has in-tree docs. I'm using it more as a public scratchpad of ideas / experiments to try that aren't well-defined enough (or known to be worth) opening as an issue yet.

mikeocool 29 minutes ago | parent

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.

wavemode 26 minutes ago | parent

You can set up automation and/or configuration such that changes to the docs folder don't require code review.

juancn 24 minutes ago | parent

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.

jdxcode 28 minutes ago | parent

i was going to say the biggest reason wasn't mentioned here, that github sets Disallow: /*/wiki*

however I think maybe this has changed? I don't see it in https://github.com/robots.txt now

david_allison 19 minutes ago | parent

They're not indexed if they're publicly editable

jdxcode 17 minutes ago | parent

also the repo needs 500+ stars https://docs.github.com/en/communities/documenting-your-proj...

_itsRoze 19 minutes ago | parent

It's likely also better that agents seeing versioned /docs can understand the context of changes to the codebase better.

knose 17 minutes ago | parent

nit: ”Using the /docs folder is the highest effort-to-reward ratio option” shouldn’t it be lowest or reward-to-effort instead?

ierukah 12 minutes ago | parent

In Forgejo, wikis are just another repo, so you have versioning there.

isityettime 4 minutes ago | parent

That's also true on GitHub: https://docs.github.com/en/communities/documenting-your-proj...

and on GitLab: https://docs.gitlab.com/user/project/wiki/

It sounds like the whole argument here is that the commits in the docs repo aren't identical commits in the source code repo. But you can ameliorate that with something like tags or submodules.

dayyan 8 minutes ago | parent

Duh.

shevy-java 2 minutes ago | parent

The Github wiki is pretty bad. However had, it is easier to use than issues and coordinating them.

If I were Github I would improve the wiki, a bit stylistically, to make it more visually pleasing to use (but not much, those designers always go overboard when making changes in my experience), but much more importantly so, to make the wiki a more flexible addition, including API-wise, usage examples, documentation and so forth. People can, in principle, do so on their own, but also from experience, most people stop doing so after a while, and then the wiki decays into outdated information. That's bad too. Spawning more issues to manage the wiki also does not work well.