4 ms·

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 pr

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 4y ago
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.
- _joel 4y ago
  Well there is (ftr I dislike confluence, but come on) https://marketplace.atlassian.com/apps/1216387/approvals-for-confluence https://marketplace.atlassian.com/apps/1216387/approvals-for...
  - origin_path 4y ago
    Interesting but is it really used? Less than 1000 installs for a product as popular as Confluence?
    - DocTomoe 4y ago
      Most use Comala: https://marketplace.atlassian.com/apps/142/comala-document-management https://marketplace.atlassian.com/apps/142/comala-document-m...
- beachy 4y ago
  > 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).
  - heydonovan 4y ago
    Disagree. A ticket should be created for any change, no matter how small. It takes seconds to write a title, body and hit submit. I've seen those small ad-hoc changes cause havoc because someone forgot to escape a single quote or didn't realize tabs were necessary and replaced them with spaces. 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.
    - The_Colonel 4y ago
      > A ticket should be created for any change, no matter how small. It takes seconds to write a title, body and hit submit. 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.
      - beachy 4y ago
        > A ticket represents a process 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.
- pxc 4y ago
  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.
  - TylerE 4y ago
    A couple of jobs ago (so we’re talking like late 00s) I rolled an internal wiki system on top of mercurial. 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.
- lukewiwa 4y ago
  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.
  - Aeolun 4y ago
    I mean. I guess? The difference between having it written down in Confluence and disappearing into the ether is academic though. Either way nobody will ever find the information again.
  - Viliam1234 4y ago
    > The last thing I want is to raise the friction for writing down documentation. 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.
    - wankle 4y ago
      Internal documentation is everyone's responsibility, not a "tech writer". External should be written by a professional, agree.
      - Viliam1234 4y ago
        "Everyone's responsibility" sounds like an euphemism for "no one really cares". When people actually care about something, they hire an expert. 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.

origin_path 4y ago

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.

_joel 4y ago
Well there is (ftr I dislike confluence, but come on) https://marketplace.atlassian.com/apps/1216387/approvals-for-confluence https://marketplace.atlassian.com/apps/1216387/approvals-for...
- origin_path 4y ago
  Interesting but is it really used? Less than 1000 installs for a product as popular as Confluence?
  - DocTomoe 4y ago
    Most use Comala: https://marketplace.atlassian.com/apps/142/comala-document-management https://marketplace.atlassian.com/apps/142/comala-document-m...
beachy 4y ago
> 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).
- heydonovan 4y ago
  Disagree. A ticket should be created for any change, no matter how small. It takes seconds to write a title, body and hit submit. I've seen those small ad-hoc changes cause havoc because someone forgot to escape a single quote or didn't realize tabs were necessary and replaced them with spaces. 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.
  - The_Colonel 4y ago
    > A ticket should be created for any change, no matter how small. It takes seconds to write a title, body and hit submit. 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.
    - beachy 4y ago
      > A ticket represents a process 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.
pxc 4y ago
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.
- TylerE 4y ago
  A couple of jobs ago (so we’re talking like late 00s) I rolled an internal wiki system on top of mercurial. 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.
lukewiwa 4y ago
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.
- Aeolun 4y ago
  I mean. I guess? The difference between having it written down in Confluence and disappearing into the ether is academic though. Either way nobody will ever find the information again.
- Viliam1234 4y ago
  > The last thing I want is to raise the friction for writing down documentation. 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.
  - wankle 4y ago
    Internal documentation is everyone's responsibility, not a "tech writer". External should be written by a professional, agree.
    - Viliam1234 4y ago
      "Everyone's responsibility" sounds like an euphemism for "no one really cares". When people actually care about something, they hire an expert. 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.