My company uses GitLab/Jira/Confluence, and two super-important features that make Confluence a winner in my mind are a) a way better story for media embedding (including photos and random uploads like PDFs, but also rich/interactive media such as LucidChart and rendering ticket lists from a Jira filter), and b) the inline discussion/annotation framework that lets you tag/nag people, ask for clarification, etc. A big part of inline discussion is that it's an instant marker for later readers that the content may not be up to date or is under discussion/review, whereas a Markdown file in some repo can have a ticket filed against it, but there's nothing in the repo that alerts a later reader to the existence of that ticket until the problem is actually resolved.

I've always been an advocate for the "markdown in the repo" scheme with CI-generated Sphinx (or whatever) docs, but these features have really won me over to the standalone wiki at least in some cases.

Non-programmers are more comfortable in the Wiki. And it's probably safer to keep them there anyway, and edits can be allowed there with fewer safeguards.

Then again I'm not sure how many non-technical folks are willing to dig into GH anyway. I've heard Issues & friends called "too confusing" for "non-technical" folks, in favor of Asana and Jira, of all things. Huge WTF from me since I'd say the opposite is strongly true regardless how "technical" one is, but that's the perception I guess.

> Basically the only thing that is left is that the wiki can be edited without supervision.

Yes, that's a significant difference. Publically contributed information (Wikipedia, Stack Overflow) can be quite good.

---

Another difference is that the wiki is not versioned with your code. (An entirely separate repo, but stil logically connected with the code repo.)

HEAD of wiki is documentation for version 1, version 2, version 3, etc. of your code.

That may be a good thing; that may be a bad thing.

I find they're rarely good, but I can see that having them live alongside code is good sometimes (as you say) but not so great when it needs to be changed independent of the code around it and you have a load 'fix markdown rendering' or 'fix typo' commits.

That feels like a failure of the tool/workflow— when you use the web UI edit button, it should put your edits on a branch for review, and make it easy to make further edits/corrections and then squash all of the piddly fixes into one big change at the end.

Fortunately, you can disable the wiki (and snippets!) on a per-project basis in at least Gitlab. Which is what we do on all our projects to ensure that everything goes through a single versioning flow.