For example, a development setup at a company or group may require a certain setup that depends upon the operating system and IDE/editor an individual developer uses. This type of information is perfect to put on wikis. It is effectively "global" information, whereas repositories contain local information. Putting information like this into a repo can increase the barrier to keeping the documentation updated and also requires source-code control access to view, which not everyone has or should have to view documentation.
In my opinion, a combination of wiki documentation plus documentation within the repository are very good. In addition to that, I often use Google's office suite or Microsoft 365 for working documents, that is documents that need to just be written, get collaborative feedback, shared between external and internal people, etc. Then, once they start to solidify and start to get more atomic updates, it makes sense to move them to the wiki or a Markdown document in a repository.
People's problems with documentation are they don't want to deal with it. It's usually not about the systems used to document things.
The main point is you need ownership and responsibility. Wikis by design don't have those things, and it shows in how people actually use them. Wiki dumpsters are popular exactly because they let people abdicate responsibility, which means docs are no one's responsibility, because no one likes writing docs.
Then each team has their own wiki page with a list of "things we care about", each of which links to a separate page that was written using a template of headings, to get minimal (and QUICK TO CREATE) documentation. The template includes about a dozen or less things like: where is the source code, who are the key stakeholders, how do you build it, how & where is it deployed, how are backups done & who is responsible for them, what are the key high-level inputs and outputs, and what else is essential that you want to know, if anything. It is OK to put "N/A" as an answer (if that is true), but all sections are to be completed before it is released.
Those things are separate from the code which is why they are not documented inside the code. They can change even when the code does not, and might sometimes be maintained by non-coders. Code doc comments are more about saying why something was done, in the code, the way it was done.
Then have new people start with the wiki. It should include a section on what to tell new people. This is a potential way to learn, and the new person can have their first task be to update portions of it as they work on new things and work with existing team members. Every attempt to change the culture should be included in the wiki (for example: "we have a rule: no new technical debt. How will we preserve that rule going forward and not just forget like we did in the past? It goes in the wiki and we review it periodically and evaluate how we are doing."). Existing team members should subscribe to change emails so they can verify non-trivial changes!
If there is a QA function, they periodically evaluate (maybe just ask the team) how well the team does at maintaining the wiki pages and following the code review checklist, and reports that to management.
If you don't have people who can or are willing to do that, might be good to ask why, and we all start by looking at ourselves.
If you destroy wikis without an alternative, they'll be replaced with one of the worse options.
But Wikis are useful for things that are shared, or that are not tied to a particular product, or don't exist in the product yet. eg - "What's the temporary workaround for this bug?" - "How do I get started as a new employee?" - "What information do we need on customer requests?" - "What's the team process for handling escalations?" - "Here's the preliminary design for this new feature"
You still need someone to update those docs, but it's nice if, eg, the manager (or product/project manager) who isn't in Git all day can do it easily instead of asking a dev to do it.
When there's a very limited set of curators, a specific topic, and a self-incentive to keep things "up-to-date" wiki's can be a great choice... mostly as like a knowledge base or internal glossary/dictionary.
For true "documentation" (if you don't take the wiki as a whole), and in the corporate world, I agree with the issues against using wiki's.
Bakes into your existing workflows, direct line of accountability to both the code reviewer and the dev.
The editing software can be anything really.
Especially if making changes to the over all architecture or introducing a new dependency! The team shouldn’t let the PR ,edge until the docs are sufficient
There may be longer write-ups, examples, etc. at the module level.
Documentation gets compiled into a docs.rs-style searchable website like so:
https://docs.rs/tokio/1.36.0/tokio/
Examples are compiled and run as part of the default CI toolchain.
So when a piece of documentation refers to some code that was moved or renamed, it is a bug to not update references in Rustdoc comments.
Comments can still get stale because some programmers write but don't read.
But they're right there on your screen next to the code you're updating.
How do you deal with cross-cutting concerns, docs that span multiple code repositories?
> some poor soul comes along and asks a question that's 5 years out of date because they found it on the wiki
This happens if there's docs in a git repo as well.
Throwing your own other comment back at ya :D
If docs aren't maintained and curated then it doesn't matter if they are in a wiki, word docs, printed pages in a file cabinet or in the repository as markdown files. Getting team discipline around updating docs is the solution, the place where they are stored is sort of trivial if that discipline exists (fwiw, I've yet to see that discipline).
With that said, there are times where docs in source control are totally viable, especially when their scoped to the repo they are located in.
Wikis do work for very large user bases, say documenting Stardew Valley mechanics. I think for very large teams, say 50, they start to make sense, especially if you're spending more time in meetings updating everyone than doing work.
Dokuwiki for example has a sane, plain text format. It can be extended relatively easily compared to Confluence (I have tried both).
Unlike certain other wikis it has access control and unlike Confluence you can edit a single paragraph or section at a time.
And finally, it is actually a wiki, wiki originally meant "quick" I think and I think calling Confluence a wiki in that context is somewhat ironic.