HN

Comments (76)

• Menu

  gwking
  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.
• Menu

  chungy
  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.
• Menu

  codazoda
  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.
• Menu

  sigvef
  Not many people know that the github wiki is actually backed by a separate "hidden" repo, and can be accessed by adding .wiki to the repo url, e.g. https://github.com/lionleaf/dwitter.wiki.gitApparently it can even do CI stuff. Still wouldn't recommend it though, for the other reasons outlined in TFA and this thread.
• Menu

  stephenlf
  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.
• Menu

  mikeocool
  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.
• a4isms
  The second paragraph neatly triggered my confirmation bias:The initial version of this post opened with “You can use the wiki or a docs folder for your GitHub project, both are valid choices” but as I wrote more, I realised that there is a single reason to use a wiki, and many more reasons not to use the wiki. So many in fact, that I consider using the wiki on GitHub is an anti-pattern.A very straightforward example of McCulloch's quote that "Writing is thinking."
• Menu

  zenoprax
  I tried to make the GH Wiki work and managed to address 6 of the 7 concerns brought up in the article using a GH Action to mirror a directory of docs. It was my first GH Action and proved to be trickier than I thought. For those who just need to expose some markdown and don't want to bother with gh-pages you might find it useful:https://github.com/super-productivity/super-productivity/blo...The generic-ness of the wiki wasn't an issue for me as I only intended on using it as a temporary measure to build up the bulk of the content and coordinate with the main dev on finding a balance between the flashy website with its guides and the less flashy docs. gh-pages is the obvious next step of course.
• Menu

  swiftcoder
  I think there is a missing pro here on the wiki side: trivial edits are trivial. Even fixing a typo in the docs directory requires PR + approvals + CI. Effectively limiting your docs contributors to folks who are comfortable with a code editor, and git, is a decision
• Menu

  hn1rig3rak
  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.
• Menu

  ghusto
  I've never understood why people even _generate_ from the docs folder. If you've written it in markdown (which they nearly always do) then it's already rendered properly in Github. Or is it because they then publish those docs somewhere else?
• bocklund
  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.
• Menu

  amai
  How do people deal with log files, images, excel files, pdfs and other binary data which they need for documentation. Do you just put everything into the repo at /docs ?
• knose
  nit: ”Using the /docs folder is the highest effort-to-reward ratio option” shouldn’t it be lowest or reward-to-effort instead?
• sholladay
  A lot of GitHub’s secondary features are like this. The Issues tab and Discussions tab are so similar, with slightly different feature sets. And users will happily use both for feature requests and bug reports, with varying degrees of quality, so then I just have yet another thing to stay on top of. I think Discussions were made to reduce noise in very busy repos, but I generally find something useful in the noise. It’s really just a way to ignore users. As a result, I always turn off Discussions and just let people file issues when they feel it’s appropriate.
• crazysim
  https://github-wiki-see.page/I've been trying for years to get the contents indexed, accessible to search engines or even AI. When I started, no wiki was ever indexed but it seems GitHub backed off a bit since then. Still, there's a bunch that is still not indexed for various reasons with valuable data in them.I do agree, most users should look into docs instead.
• spider-mario
  The section “How about the reasons not to use the wiki?” is written rather confusingly. It mixes points that apply to the wiki (“The documentation isn’t available locally when someone clones your repo”) and points that apply when not using the wiki (“Documentation edits get the same treatment as code”) without making it clear which one is which – you have to infer it yourself.
• fny
  > You can get to the wiki contents in a single click from anywhere in the repo There is no 2.2. Non-technical people can work with tools they know.3. You may not want to deal with pull, push, merge for every edit.4. You may not want to deal with PRs for every edit.5. Setting up `/docs` takes work. Wikis are just there.Mintlify and others turned this sort of convenience into a business.
• Menu

  jjice
  I agree, but my only gripe is I hate the ceremony required for doc-only updates. It needs a review and CI. The review is a good thing in most cases (want your docs to be correct), but that often takes my team like two days (I'm realizing this is likely our fault now that I'm typing this). For CI, I've just added in a step to all our GitHub actions to skip Markdown only changes. Anyone have any better ideas?
• a1o
  I really wanted the wiki to at minimum have directories so they would be easier to structure and allow even for major versions that are maintained in parallel.
• Menu

  jdxcode
  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
• azatom
  To consider, there are different docs:in repo (can be wiki format):- dev docs- user manualdifferent repo:- community usage wiki
• anon
  undefined
• Menu

  preisschild
  In Gitlab the wiki is just a separate git repo. Is this not the case with GitHub?
• flobosg
  (2022)
• esafak
  Yes, and the rest of it is too; there's another outage today and my CI is blocked. I guess I can read the wikis while I wait, eh?? https://www.githubstatus.com/
• shevy-java
  The Github wiki is pretty bad. However had, it is easier to use than issues and coordinating them. Github issues require too much cross-communication and not everyone has the time to meta-coordinate many different issues in many different projects. A wiki lowers the entry-barrier too, so the idea of a wiki is, in principle, good.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.
• Menu

  ierukah
  In Forgejo, wikis are just another repo, so you have versioning there.
• 00kee0d
  You own it now, I'll quote you on that!
• thedefaultman
  [flagged]
• arkonvault
  [flagged]
• dayyan
  Duh.
• _itsRoze
  It's likely also better that agents seeing versioned /docs can understand the context of changes to the codebase better.