Never use a wiki for anything. Wikis are the number one worst form of documentation. They are worse than no documentation. Wikis explicitly destroy the concept of ownership and responsibility, and without those, what you get is a big pile of outdated, unorganized trash that no one maintains. Destroy wikis.
There are downsides to wikis, but suggesting to never use them is quite extreme. What do you propose instead? Putting everything into the repository doesn't always make sense.
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.
Five years and 80% employee turnover from now, your wiki will be a completely unsearchable pile of outdated trash from employees who don't work there anymore. Wikis are not documentation, they are dumpsters you can rummage through and try to find a nugget of wisdom. Don't make your new employees rummage through dumpsters.
Just because someone is bad at curating documentation doesn't mean it is inherent to wikis. Wikis and repository-sourced documentation are under the same constraints of requiring curation. There is no "automatic" documentation that happens. It has to be written, updated, maintained, and publicized.
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.
Sure you could re-invent source control, ownership models, bug tracking, change review and merge processes in a wiki. Or you can use the tools that we already have for that.
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.
I like to think of it as a garden, you're continually planting and pruning. When things die you remove them. You do your best to figure out where to plant new things.
In my experience a wiki is useful to improve the bus count (what happens if key people are hit by a bus). To keep it maintained, establish a culture of using a code review checklist (with things like: does the documentation need to be updated? Is it properly tested? Did the tests fail when the code is intentionally broken or incomplete? Can someone who was not part of the design discussion (nor given any verbal explanation) understand this well enough to maintain it?. Enforce that checklist and improve it (in the same wiki) with time. I think it becomes a big net timesaver and improves quality of life.
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.
You seem to be thinking specifically about documentation for one particular project, eg API docs. And in that context I'd agree.
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.
I will counterpoint slightly to this... I'm currently trying to set up a wiki for my house documentation (eg: TechStack, QuarterlyMaintenance, ValuableAssets, BackupRestore, HomeAutomation, etc...).
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.
The same tool you use for merging code, with the same ownership & maintainer model. In our case, that's git, and our docs live in markdown files in a docs/ folder.
Five years and 80% employee turnover from now, your git docs will be a completely unsearchable pile of outdated trash from employees who don't work there anymore
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).
Yeah of course you can have bad docs in any system. But wikis actively encourage a bad ownership model (i.e. none). You could put in a bunch of work to build up an ownership and change review system around a wiki, I guess, but we already have tools for that. Use those instead!
I agree with you but I also don't see how using source control is a solution to any of it. In my experience, repos go orphan quite regularly in large companies. In the end of the day, documentation requires maintenance.
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.
Slack message received: "Hey, I was reading the documentation and walking through the process and encountered this <bug> and this <typo>. Can you fix <this> and re-export the documentation? Thanks!"
I mean, yeah! That's ideal! If someone doesn't have write access to a repo, then they shouldn't be able to edit the docs for the stuff the repo contains without review either. Just like if they found a bug in the code, they should open a ticket for the problem and the dev responsible for those docs will go fix it.
Yeah, you'll have to sit down and answer that question. Where do docs live? Who is responsible for maintaining them? Wikis let you skip all that, throw the docs into the dumpster, and forget about it until some poor soul comes along and asks a question that's 5 years out of date because they found it on the wiki. Wikis are not a solution, they're giving up.
So what do you suggest? Maybe a dedicated technical writing team? But then you might as well just give them responsibility for a wiki, it doesn't have to be a repository.
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.
I am not OP but I push very hard for docs as code.
Your pull request should change content in the ‘src’ folder *and* the ‘docs’ folder.
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
And ... this can then still be a wiki, right? Not saying that they are the best form, but I think you can combine wikis with people who (have to) take responsibility for certain articles.
I remember an anecdote by Will Wright where he said that in large teams they were spending 3 hours in meetings for every hour of work. Wikis were one fix.
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.
This is my experience as well. I don't say it can't be done, but I've seen this happen multiple times. And with GitHub wikis, in particular, it makes it very hard to have docs tied to specific versions of the software.
Comments
Never use a wiki for anything. Wikis are the number one worst form of documentation. They are worse than no documentation. Wikis explicitly destroy the concept of ownership and responsibility, and without those, what you get is a big pile of outdated, unorganized trash that no one maintains. Destroy wikis.
There are downsides to wikis, but suggesting to never use them is quite extreme. What do you propose instead? Putting everything into the repository doesn't always make sense.
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.
Five years and 80% employee turnover from now, your wiki will be a completely unsearchable pile of outdated trash from employees who don't work there anymore. Wikis are not documentation, they are dumpsters you can rummage through and try to find a nugget of wisdom. Don't make your new employees rummage through dumpsters.
Just because someone is bad at curating documentation doesn't mean it is inherent to wikis. Wikis and repository-sourced documentation are under the same constraints of requiring curation. There is no "automatic" documentation that happens. It has to be written, updated, maintained, and publicized.
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.
Sure you could re-invent source control, ownership models, bug tracking, change review and merge processes in a wiki. Or you can use the tools that we already have for that.
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.
I like to think of it as a garden, you're continually planting and pruning. When things die you remove them. You do your best to figure out where to plant new things.
In my experience a wiki is useful to improve the bus count (what happens if key people are hit by a bus). To keep it maintained, establish a culture of using a code review checklist (with things like: does the documentation need to be updated? Is it properly tested? Did the tests fail when the code is intentionally broken or incomplete? Can someone who was not part of the design discussion (nor given any verbal explanation) understand this well enough to maintain it?. Enforce that checklist and improve it (in the same wiki) with time. I think it becomes a big net timesaver and improves quality of life.
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.
Wiki is third-worst. Even worse than wiki is Slack. Even worse than Slack is "ask so-and-so".
If you destroy wikis without an alternative, they'll be replaced with one of the worse options.
The arch wiki for example is not perfect, but still helpful to me (and Wikipedia in general). I would not overgeneralize.
You seem to be thinking specifically about documentation for one particular project, eg API docs. And in that context I'd agree.
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.
I will counterpoint slightly to this... I'm currently trying to set up a wiki for my house documentation (eg: TechStack, QuarterlyMaintenance, ValuableAssets, BackupRestore, HomeAutomation, etc...).
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.
So what do you use instead?
The same tool you use for merging code, with the same ownership & maintainer model. In our case, that's git, and our docs live in markdown files in a docs/ folder.
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).
Yeah of course you can have bad docs in any system. But wikis actively encourage a bad ownership model (i.e. none). You could put in a bunch of work to build up an ownership and change review system around a wiki, I guess, but we already have tools for that. Use those instead!
I agree with you but I also don't see how using source control is a solution to any of it. In my experience, repos go orphan quite regularly in large companies. In the end of the day, documentation requires maintenance.
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.
For us, documentation lives in Markdown in Rustdoc comments above the things they document.
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.
Fossil SCM, which comes up on HN every once in a while, rolls a wiki and issue tracker in the same repository as source code.
https://fossil-scm.org
This doesn't work for documentation that needs to be viewed by people without source-code control access.
Sure it does. As part of your CI process, build your markdown into HTML or whatever and host it.
Slack message received: "Hey, I was reading the documentation and walking through the process and encountered this <bug> and this <typo>. Can you fix <this> and re-export the documentation? Thanks!"
I mean, yeah! That's ideal! If someone doesn't have write access to a repo, then they shouldn't be able to edit the docs for the stuff the repo contains without review either. Just like if they found a bug in the code, they should open a ticket for the problem and the dev responsible for those docs will go fix it.
So in order to find documentation, you need to know which repo to look in?
How do you deal with cross-cutting concerns, docs that span multiple code repositories?
Yeah, you'll have to sit down and answer that question. Where do docs live? Who is responsible for maintaining them? Wikis let you skip all that, throw the docs into the dumpster, and forget about it until some poor soul comes along and asks a question that's 5 years out of date because they found it on the wiki. Wikis are not a solution, they're giving up.
So what do you suggest? Maybe a dedicated technical writing team? But then you might as well just give them responsibility for a wiki, it doesn't have to be a repository.
This happens if there's docs in a git repo as well.
I am not OP but I push very hard for docs as code. Your pull request should change content in the ‘src’ folder *and* the ‘docs’ folder.
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
Assign domains of the app to developers, the people doing the code reviews require people to update documentation.
Bakes into your existing workflows, direct line of accountability to both the code reviewer and the dev.
The editing software can be anything really.
And ... this can then still be a wiki, right? Not saying that they are the best form, but I think you can combine wikis with people who (have to) take responsibility for certain articles.
A wiki
I remember an anecdote by Will Wright where he said that in large teams they were spending 3 hours in meetings for every hour of work. Wikis were one fix.
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.
This is my experience as well. I don't say it can't be done, but I've seen this happen multiple times. And with GitHub wikis, in particular, it makes it very hard to have docs tied to specific versions of the software.
So stop using Confluence?
I think that is a better idea than demanding everyone ditching all wikis.
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.