[simpixelated]

One point that I disagree with is "Every question asked in an internal Slack is a policy failure. It means the existing information systems failed to deliver an answer, and the user falls back to manually asking the hive mind's tacit knowledge." I find it's usually a failure of the doc search mechanism. It's much faster to ask humans a vague question than try to form the right search query for the internal doc system, which is usually much much worse than Google.

This can be solved by making docs public, but also by having people respond with a link to the docs. So Slack can still be a good interface to Q&A, as long as a single answer is documented.

[valand]

I agree. Everyone's notion of documentation, its placement and role, can be different.

Some workplace relies on self-documenting code, some would require technical specs to be written in an internal wiki, some uses function/class/module headers.

It is inevitable that someone would ask how should I read the documentation, and any question on slack should be treated as a chance for improvement and better UX for devs.

Repeated questions from different people is a sign of the lack of improvement in the same area.

My usual go-to method to partially solve this issue is to challenge newcomers to write the question they asked and the answer for it, including how to write it, or make change to an existing one, so that other newcomers will find it easier to onboard.

[jcelerier]

honestly, it also sounds like author's dream place to work is a Brazil-like bureaucracy. ugh.

[MaxBarraclough]

That wasn't my take. Good documentation doesn't equate bureaucracy.

20 years ago, Spolsky wrote a blog post about how good documentation need not be unreadably dry and soulless. [0] From which:

> Rule 1: Be Funny

> Yep, rule number one in tricking people into reading your spec is to make the experience enjoyable.

[...]

> if you work in a company where people will respect you less because your specs are breezy, funny, and enjoyable to read, then go find another company to work for, because life is just too damn short to spend your daylight hours in such a stern and miserable place.

I'm not sure I'd go quite that far - it seems a bit much to leave an otherwise agreeable position just because they insist on humourless documentation - but I think he makes some important points.

[0] https://www.joelonsoftware.com/2000/10/15/painless-functiona...