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

51–60 of 70 posts

Re: Duty to Document (2023)

#51

Post by jstanley »

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…

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

Re: Duty to Document (2023)

#52

Post by maxvt »

jumpman500 wrote: post #33

The code, tests and data is the documentation. If the code is clear the documentation should be short description of features and purpose. Explaining how to setup a development environment is nice for onboarding. Everything else is noise and leads to worse understanding. You have a duty to document but you also have a duty not to document irrelevant details or workarounds that aren’t real solutions. Bad documentation…

I would not suggest people to follow this in 2024 if they are building any system of non-trivial scope and expect it to be adopted by others who are not required to adopt it.

Back in 2017, I compared "code as documentation" to being dropped into on the street of an unfamiliar city, while a good documentation can serve as a map of the city. [1]

Nearly all recent successful efforts for large new systems understand the value of both high-level overviews and detailed examples / onboarding materials to make adoption easier. When solutions to a certain problem are abundant, people do not need to settle for options that do not have great supporting documentation of the four primary kinds. [2]

[1] https://speakerdeck.com/maxvt/i-got-a-lot-of-problems-with-i...

[2] https://documentation.divio.com/

Re: Duty to Document (2023)

#53

Post by dllthomas »

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…

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

Re: Duty to Document (2023)

#54

Post by eschneider »

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…

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.

Re: Duty to Document (2023)

#55

Post by bad_username »

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…

> After the duty to document, comes the duty to expose it

And then to maintain it. Which is hard.

Re: Duty to Document (2023)

#56

Post by anatnom »

tom_ wrote: post #50
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.

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 '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 and search for .

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.

Re: Duty to Document (2023)

#57

Post by bad_username »

jumpman500 wrote: post #33

The code, tests and data is the documentation. If the code is clear the documentation should be short description of features and purpose. Explaining how to setup a development environment is nice for onboarding. Everything else is noise and leads to worse understanding. You have a duty to document but you also have a duty not to document irrelevant details or workarounds that aren’t real solutions. Bad documentation…

Documentation to code is what a database index is to database data. You can do full table scans but indices speeds up things by orders of magnitude. Similarly you can piece a big project picture together by reading all the code, but it will never be as fast as reading a good architectural overview or a description of concepts.

But, as a corollary, do not document what can be inferred quickly by looking at the code. I think that doc generators from code doctrings are not very useful.

Re: Duty to Document (2023)

#58

Post by nicbou »

sakjur wrote: post #38
nicbou wrote: post #25

Earlier quoted context omitted.

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

> An LLM won't make phone calls. That is an interesting idea that I’m a bit worried could lead to more spammy ‘content’. I’d be surprised if the combination of LLM chat technology, voice recognition, voice generation, and affordable SIP trunks wouldn’t lead to someone deciding to start a website staffed by bots interviewing subject matter experts and writing articles based on those conversations. Isn’t Google doing t…

I'd like to see it do the sort of journalistic legwork my job involves. This is a moat I don't expect AI to cross soon.

Re: Duty to Document (2023)

#59

Post by jmole »

anatnom wrote: post #56
tom_ wrote: post #50

Earlier quoted context omitted.

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…

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

Re: Duty to Document (2023)

#60

Post by Min0taur »

I really appreciate the simplicity and clarity of your call to action.

I'm reminded of a bit from Ursula K. Le Guin that I have always found quite poignant:

“The explorer who will not come back or send back his ships to tell his tale is not an explorer, only an adventurer; and his sons are born in exile.”

Post reply on HN