Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Duty to Document (2023)

nicolasbouliane.com

Post reply on HN
Print view View original

41–50 of 70 posts

Re: Duty to Document (2023)

#41

Post by CrypticShift »

nicbou wrote: post #25
CrypticShift wrote: post #19

After the duty to document, comes the duty to expose it : - How do you format that doc ? which is particularly relevant if you'd like to roam around. the author's Berlin guide is a good example [1] - How do you find exactly what you want ? Some say that there's no longer (or lesser) need to document because we have LLMs. I would argue the exact opposite : Given their ability to streamline the retrieval process (into…

> Some say that there's no longer (or lesser) need to document because we have LLMs. What will you train the LLM on? It has to get the information from somewhere . This is a point I'm supposed to make next month in a panel about using AI to help immigrants. An LLM won't make phone calls.

In a sense, we may have less need to create "formal, structured documents." Even today, many companies archive a large part of their informal conversations (meetings, emails, Slack...) in addition to "memos" and other short docs. The LLMs may get their data from there. Imagining a future where even open everyday conversation is recorded is a privacy nightmare, so this may not always be possible in less digitized environments (immigrants assistance ? I don't know)

Also, proponents of AGI believe that advanced forms of AI will require less training to be "creative," or at least to "infer/reason" on "low-level data" in order to create "higher-level" knowledge.

Re: Duty to Document (2023)

#42

Post by andrewaylett »

bluGill wrote: post #6

Where can I document things? If I put it on my person blog google won't find it - preferring instead SEO blogspam. If I document something but nobody reads it (including me), then the effort was wasted.

I put my stuff on my own website, despite my analytics saying I get next to no traffic. It's not a waste of time, because the largest benefit accrues to me when I write it. And if no-one reads it then hopefully I can avoid being over-pretentious while still having something to link folk to if any of my random thoughts ever become relevant.

Case in point: I'm not even going to link to it from this comment. It's easy enough to find for anyone who actually wants to find it :).

I should probably publish more, though.

Re: Duty to Document (2023)

#43

Post by paxys »

avg_dev wrote: post #13

Good thought, but > I figure that if you have knowledge that could benefit thousands of people, and it costs you next to nothing to share that knowledge, it’s your duty to do it. As someone who has written a lot of docs over the years, there can often be a very high cost in terms of time and effort to document something.

Exactly. If it was truly zero cost then everyone would be doing it. In reality concisely describing a complex system is more difficult than building one.

Re: Duty to Document (2023)

#44

Post by penguin_booze »

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.

Re: Duty to Document (2023)

#45

Post by groby_b »

penguin_booze wrote: post #44

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' d…

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".

Re: Duty to Document (2023)

#47

Post by kstrauser »

xyzelement wrote: post #39
kstrauser wrote: post #34

Earlier quoted context omitted.

That's exactly the sort of thing I document for myself. Getting my thoughts together enough to explain them to a hypothetical, likely-nonexistent reader gives me a lot of clarity into my own thinking.

I call that "journaling" - I have a lot of physical paper journals that I wouldn't expect anyone to read - they so far have been write-only as a way to explore or clarify a topic for myself. I say "so far" because potentially I could read through them for valuable ideas that can be re-shaped for an audience. "Documentation" in my mind does have an audience that you hope can benefit from what you are writing. The diff…

That's such a blurry line, isn't it? And there are so many approaches. I tend to journal such things in the form of personal wiki pages documenting both my thoughts and why I think them, with links to sources. Basically, I'm writing to myself, but in a way that I could restore state after getting amnesia. It's probably overkill but it helps me think things through.

Re: Duty to Document (2023)

#48

Post by JackFr »

xyzelement wrote: post #17

I’ve been thinking recently about documenting my journey towards religion - what it has been like starting from a hyper-logical, secular-intellectual perspective and layering the religious wisdom atop that foundation. Religion itself (Judaism in my case) has a lot written about it obviously and I am not reaching any novel conclusions but it seems like the winding path I I followed could be helpful for others. To be c…

You'd not be the first to tread that path:

https://en.wikipedia.org/wiki/Confessions_(Augustine)

https://en.wikipedia.org/wiki/The_Seven_Storey_Mountain

Re: Duty to Document (2023)

#49

Post by pphysch »

Documentation is good for the organization, but requires a sacrifice from the individual. It takes (a little) time to document properly, and effective documentation erodes the knowledge gap of the author, impacting their job security.

Re: Duty to Document (2023)

#50

Post by tom_ »

penguin_booze wrote: post #44

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' d…

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.
Post reply on HN