undefined | Better HN

0 pointsanatnom2y ago0 comments

In several organizations, I have been the person who writes high-quality documentation. I enjoy writing (and reading) good technical documentation, so this is a self-appointed responsibility. I agree that people aren't interested in documentation for something they either probably-know or probably-don't-need-to-know, so a vacuous thumbs-up emoji is all I expect when creating documentation.

However, the "you can hand out a link" part is what really grinds my gears. The expectation of my former coworkers that it is <someone else>'s job to find the proper documentation pages for them was quite exasperating. '@anatnom can get you the docs for this' and similar messages is...disheartening. My workflow was always to go to <internal docs page> and search for <relevant term>.

Perhaps there are organizations where the documentation-writers are not also encumbered with being the link genie, but I've not had that experience. I wish I could teach a dev to fish, but instead I have to hand out fish all day.

0 comments

verve_rat2y ago

People won't respect you unless you stand up for yourself. Get a little bitchy, get a little passive aggressive, push back and publicly shame some people.

Link to instructions that tell people how to search the documentation. They are wasting your time because they can't be bothered themselves. It is up to you to stop being the doormat.

It does suck that you can't expect grown arse adults to do something as simple as ctrl-f a page before bugging other people. But I have learnt the first response to any request for help should be "show me the research you have so far". Which, 90% of the time, is followed up with "let me teach you how to research this".

University (and other schooling) used to teach people how to learn, now that seems to be the responsibility of other employees.

Or, hand out fish every day and get used to the fact nothing will change.

jmole2y ago

I think LLMs will quickly assume the role of fish-hander-outer, even if they aren't actually writing useful documentation themselves.

j / k navigate · click thread line to collapse