The other thing about documentation is that it inevitably goes stale.

So the question becomes: is no documentation better or documentation that can be - potentially - entirely out of date, misleading or subtly wrong, because eg they documented the desired behavior vs actual behavior (or vice versa).

I'm generally pro documentation, I'm just fully aware that internal documentation the devs need to write themselves and for themselves... Very rarely gets treated with enough respect to be trustworthy.

So what it comes down to is one person spearheading the efforts for docs while the rest of the team constantly "forgets" it, until they decide it's not worth the effort as soon as the driving force either changes teams or gave up themself.

  > documentation is that it inevitably goes stale.

There's two helpful and minimal mitigating strategies here

  1) dating/versioning
     Provides hints that they might be stale if we can identify if they're old. Easy to diff a function between versions when something seems wrong

  2) In code documentation (e.g. docstrings)
    While not as good as a manual, it's not too difficult to write docstrings *while* coding. 

Also, I'm pretty certain we've all experienced a choice between two tools where our choice prioritized documentation. Docker is a great example (it's even RedHat's business model!). There's many container systems, many that can even do more! But take systemd-nspawn (and vm). Very poorly documented stuff and not many examples to learn from.

I wanted to make that reminder because UX is important to the business.

I think there’s a natural tendency to want to document the process for those who have the work assigned to them, and some folks will self-assign it because they see the value.

Knowledge transfer through technical writing doesn’t always manifest itself if it isn’t part of the work process at the time you have that in your mental context. It’s hard to have that context to write the docs if you’re context switching from working on something else or not involved at that level, so it’s hard to just drop in to add docs if there isn’t some framework for writing ad hoc docs for someone to fix up later.

I don’t have experience at traditional employers though so I can’t speak authoritatively here. I’m used to contracts and individual folks and small business. Having human readable documents is important to me because I’m used to folks having things explained on their level, which requires teaching only what they need and want to know to get their work done. Some folks don’t even know what they need when they ask me for help, so that’s its own process of discovery and of documentation. I’m used to having to go to them where they are and where the issue is, so there was no typical day at the office or out of it. Whatever couldn’t fit through the door, I had to go to myself. I’ve had to preserve evidence of potential criminal wrongdoing and document our process. It taught me to keep notes and to write as I work.

I think most places do have some kind of process for doing this, and I suspect the friction in doing the thing is part of the issue, and the fact that it’s difficult thankless work that doesn’t show up on most tracked metrics is part of the issue.

If docs were mandated they would get done. If someone’s job was to make sure they were done well, that would help. I guess folks could step up and try to make that happen and that might be what it takes to make that happen.

>The other thing about documentation is that it inevitably goes stale.

Not if you generate reference docs from code and how-to docs from tests.