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