That's the average wiki. It's a commons and a tragic one. To make docs work you have to treat it more like a codebase: clear ownership, standards, review processes, approvals, up front design, refactoring efforts etc.
Maybe true in large orgs.
But for smaller companies what I've seen is usually paralysis.
e.g. someone notes a problem (maybe just a typo) in the doc. Can they fix it within seconds? If instead they need to raise a ticket then most likely it ain't happening. They move on, and the next person experiences the same problem.
IMO the default should indeed be towards everyone committing at will. Yes that will result in the occasional snafu. Fix that when it happens. (obviously not good practice for the operating manual for a nuclear power plant - but for a <500 person Saas company it is).
Mandating a Jira ticket for simple typo fixes is overkill. But if you make it easy to create a PR directly on the documentation file, without leaving the tab, I don't see an issue. This is already a Github feature.
Overall the comments on this page fall into 2 camps, people who've tried it all and found what works is discipline and those who are still trying it all.
The default for Confluence is just that, everyone commits at will. There is no structure, tons of duplication, no standards when it comes to naming, formatting, audience, etc. I'm a huge fan of markdown/plain-text solutions, only because linters can be run that force you down one happy path. I don't believe Confluence has linters at all.
A ticket represents a process (otherwise it has no added value over git commit message) and thus creates much more work than a couple of seconds.
Yep, and that process also involves other people, to review/ approve the fix to the typo.
It then goes from being a few seconds of elapsed time and actual time (to just commit a fix to the typo) to taking hours, days or weeks of elapsed time and hours of actual time and forcing context switching on, and interrupting the workflow of, all of people involved.
It's hard enough to get technical minded people to contribute to a git (or style) based knowledge base.
Pick your poison I guess but I'm quite happy to have testers/BAs/directors/etc able to quickly jot down thoughts roughly than have it disappear into the ether.
A better solution might be that anyone can write the documentation, and there is a maintainer who constantly refactors the wiki to keep it legible. Makes sure the information is not duplicated, adds hyperlinks to things, etc.
Why do you hire software developers, instead of making software development everyone's responsibility? Is that because most people suck at software development? Well, most people suck at writing documentation, too.
It was a directory of files - I think plain text with a few wiki shortcuts, but might have been some sort of early Markdown.
The editing form was basically a text area on top of mercurial.
Similarly things like the edit log were basically dumping the mercurial output into html.
No clue how long it lasted, but it was still in regular use when I left in 2012.
Wrote the whole thing in a few afternoons.
