[cmdrriker]

Does it matter what tool you use to write documentation? Confluence gets a lot of sh*t because its in the grown-up camp of tools but I know people who've got problems even with nano.

It's incumbent upon all users or members of the team to use the common tool along with agreed upon standards. Otherwise even if you wrote documentation in your own hemoglobin, no one would touch it either.

Some manager prob chose _________ as the tool for ticketing, documentation, etc not because it was good at ______, or _______ but because it fulfilled their action plan to have something, anything in place so that if the universe goes supernova, well some stuff was written down.

In my journey it seems that nobody is willing to criticize Edward Teach for the lousy treasure map he left, but rather we make fun of those who're still looking for his stuff.

[origin_path]

It does matter because the issue with wikis (not just confluence) is there's no approval or review workflow. Imagine trying to write a large program in which everyone could just commit at will, with no review process whatsoever, and where nobody had made any decisions about design up front. There'd be duplication, dead code, the organization would be crazy.

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.

[beachy]

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

[lukewiwa]

The last thing I want is to raise the friction for writing down documentation.

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.

[_joel]

Well there is (ftr I dislike confluence, but come on) https://marketplace.atlassian.com/apps/1216387/approvals-for...

[pxc]

There are some really nice git-based wiki systems out there, and one is built into GitHub and GitLab. If you want that type of workflow for your wiki, it's easy to get.