Comment by penguin_booze | Hacker News Reader

Comment by penguin_booze | Hacker News Reader

At all the places I've worked, I've put my own time to document how things work. These are often HTML pages, with links to the source code, pointing at the exact point where the action happens. I strive to offer a narration of what happens from startup to shutdown. I do this as and when I discover things. Over time, the documentation grow in size, inadvertently forming a 'what I'd like to have found when I started' document--an unofficial refrence manual. I put even more time in organizing the information presented. I draw block and sequence diagrams. I then share the links with my teams and managers at the time.

Guess what? Other than the multiple emoji reactions, appreciative and thanking comments I get at the time of sharing, nobody bookmarks them or even refer back to them. People completely forget such a document even exists. Then, in team chat, someone asks 'does someone know does X works?'. I roll my eyes and share a link to my document. Rinse and repeat.

I say this not to say that I deserve more recognizition, but to lament that people don't care as much I think they should. By extension, they don't care whether someone wrote things down, either.

People care. At the individual level. In the abstract. But there are two obstacles that keep them from doing the right thing.

One is that without discoverability of those docs (in a non-legal sense ;) it's a doomed effort, because ... there are too many docs. Even if everything is woefully underdocumented, it's still too much to just find the right thing. (There are simultaneously too few docs in most orgs, so the corpus you could train search on is too small to be truly impactful for any ML solution).

The second missing part is a set of clear expectations that folks do this, and rewards if it's done exceptionally well. Or, really, a culture around document, though these two are the skeleton you hang a culture off. And if that culture doesn't exist, most people will not write docs - the org is sending a clear signal it doesn't value them, and it takes a lot of effort to do things you know won't be rewarded or valued.

The second one looks like people don't care. But really, it's leadership sending a clear signal of "Please don't care, this is not important to us".

The problem is that this sort of documentation is often incorrect, incomplete, or out of date, so people learn not to trust it.

> The problem is that this sort of documentation is often incorrect, incomplete, or out of date, so people learn not to trust it.

That's not a problem with the documentation, it's a problem with those people's attitude.

I find "incorrect, incomplete, or out of date" documentation extremely valuable. Documentation is always just one data point in a constellation of data points needed to understand something, but it can often fill in important gaps that can't be filled in any other way. Not having it always leaves you off in a worse situation.

> The problem is…

…multifaceted from my experience.

1. At the org-level…

  - no standard doc tooling
  - no easy-to-remember URLs
  - no simple permalinks
  - no easy-to-update “pages” (AKA markdown-based)
  - they certainly don't train employees how to create good docs
  - minimal if any doc standards

2. At the leadership-level…

  - they don’t incentivize good documentation
  - they don’t set the expectation that “everybody writes”
  - they don’t document themselves!

It’s no wonder docs are scattered, out of date and untrustworthy!

The worst environment is when people don't bother to update documentation. That's when you know you have a garbage shop.

Nobody reads documentation at the time, and you shouldn't expect it. It's there so that when somebody asks about something that's got a documentation page for it, you can hand out a link.

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.

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

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.

Same here. I work on lots of different things and I'm completely switching project context every few weeks and new things need doing. Like you, I write "the doc I wish I had the first time I started" and when I go back to that project, there it is waiting for me. :)

And yeah, things have changed from last time and it's no longer quite right, but it's hella better than starting again from scratch and no big deal to update.

And yeah, if other folks as "how does 'X' work?" I send them a link, but really, I'm mostly just documenting for myself.

> with links to the source code, pointing at the exact point where the action happens

I like to do these kinds of links in a way that marks both the reference and the referent, rather than the more typical unidirectional html style. It means less busywork to update as code moves around, and it increases discoverability. It also makes it easy to do things with tooling like surface relevant references/referents during code review.

Reply on news.ycombinator.com