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

61–70 of 70 posts

Re: Duty to Document (2023)

#61

Post by judemelancon »

paxys wrote: post #43
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.

Documentation absolutely has a cost, but that last sentence is a substantial overgeneralization. Counterexamples include a search engine, a quilt, an impact driver, and a box of a basic LEGO bricks.

Re: Duty to Document (2023)

#62

Post by simonw »

> If you learn something the hard way, share your findings with others. You have blazed a new trail; now you must mark it for your fellow travellers. Sharing knowledge is an unreasonably effective way of helping others.

This is a really nice philosophy. It's one of the reasons why I have my https://til.simonwillison.net TIL site - any time I search for something and can't find the answer is a hint that there's a tiny gap in the internet which I can help fill.

Re: Duty to Document (2023)

#63

Post by tivert »

jstanley wrote: post #51
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.

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

Re: Duty to Document (2023)

#64

Post by akira2501 »

I feel like I disagree. I don't have a "duty" to do anything. If I was able to find the information and make a discovery, then others are capable of it too, and there is a lot of value in allowing people to experience that process on their own. If you ask me, I'll tell you, but I feel leaving the question open for others can often be worth doing.

I think the author makes a far finer point on one of their linked project pages, All About Berlin:

"All About Berlin is my answer to the hastily written SEO spam that pervades the web. It proves that a website can be successful without annoying the everliving crap out of its readers.

It has no ads, no paywalls, no dark patterns, no newsletter pop-up, no coercive cookie notice, no call to action, no comments, no promoted content, and no share buttons. It gives straight, honest answers for free. That’s it."

This is more useful thinking about the core issue, I feel. You don't have a duty to document, but you do have a duty to not intentionally obscure useful information in order to derive a personal benefit from that obscurity. No small irony that this is on a site that designed to take _government_ information and make it more accessible to citizens that have already paid for it.

Re: Duty to Document (2023)

#65

Post by verve_rat »

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…

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.

Re: Duty to Document (2023)

#66

Post by justincredible »

akira2501 wrote: post #64

I feel like I disagree. I don't have a "duty" to do anything. If I was able to find the information and make a discovery, then others are capable of it too, and there is a lot of value in allowing people to experience that process on their own. If you ask me, I'll tell you, but I feel leaving the question open for others can often be worth doing. I think the author makes a far finer point on one of their linked proje…

[dead]

Re: Duty to Document (2023)

#67

Post by xyzelement »

JackFr wrote: post #48
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

These are great suggestions. Thank you!

Re: Duty to Document (2023)

#68

Post by hm-nah »

jstanley wrote: post #51
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.

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

Re: Duty to Document (2023)

#70

Post by EMCymatics »

jstanley wrote: post #51
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.

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