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

11–20 of 70 posts

Re: Duty to Document (2023)

#11

Post by 70rd »

zero-sharp wrote: post #8

I work at a small finance firm where the projects were ran by one or two people for probably a decade. They didn't rely on databases, or any programming, up until 6 years ago or so and spreadsheets were how they got work done. So when I have to figure out how to do something, I have to click through probably a dozen spreadsheets and track Excel formulas/ad hoc calculations. There's no documentation, presumably becaus…

Most enduring sofware is always those "one-off prototypes" that people cook up over a few days.

Re: Duty to Document (2023)

#12

Post by sodapopcan »

NoboruWataya wrote: post #4

As someone who likes to tinker with code and learn new things but finds it very difficult to actually bring a project to a level of polish where I feel happy announcing it to the world, I have found that sharing knowledge is an easy and effective way to contribute back to the commons. I've written a small number of blog posts sharing things I've learned during my tinkering, which other people appear to have found qui…

> finds it very difficult to actually bring a project to a level of polish where I feel happy announcing it to the world

Which of course reminds me of the Reid Hoffman quote: "If you are not embarrassed by the first version of your product, you’ve launched too late."

I know the context is a little different, but still makes me think of it :)

Re: Duty to Document (2023)

#13

Post by avg_dev »

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.

Re: Duty to Document (2023)

#14

Post by zvmaz »

Documenting has not only tremendously helped others in their work, but also myself. Furthermore, I do not want to remember from memory how I debugged a particular problem, instead I check the documentation, and get it over with.

Re: Duty to Document (2023)

#15

Post by tikkun »

Reddit comments are a good example of this. To anyone that has ever posted a solution in response to a reddit question, thank you. You've saved me a lot of time and frustration!

For the original post, I think duty is too strong and I don't like being told what to do, but I get the idea and I too hope more people document things!

Re: Duty to Document (2023)

#16

Post by vitiral »

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.

Also, there is cost to you to maintain docs and a cost to others if you don't.

Some things are near universal and always useful. Documenting by creating a full working example with minimal dependencies will stand the test of time.

I'm not saying don't document. Even a list of notes, clearly marked as such, can be helpful.

Re: Duty to Document (2023)

#17

Post by xyzelement »

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 clear it’s a daunting challenge - because there’s no single point answer but the narration is a journey of its own as well.

Re: Duty to Document (2023)

#18

Post by [deleted] »

NoboruWataya wrote: post #7
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 agree this is a challenge - Medium used to be okay for this as it could give you good reach, but I feel like it's become overly saturated with low-effort content lately.

[deleted]

Re: Duty to Document (2023)

#19

Post by CrypticShift »

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 a naturally "human" chat), every documentation's worth is actually magnified by LLMs.

[1] https://nicolasbouliane.com/projects/all-about-berlin

Re: Duty to Document (2023)

#20

Post by lo_zamoyski »

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.

Indeed. To elaborate...

1) Documenting things does cost, especially time. Writing good, clear, cohesive documentation is even more costly. Bad documentation can be costly by consuming the reader's time beyond what is justified.

2) Documentation often needs to be updated and therefore maintained. This is costly.

3) Failure to maintain documentation can leads to even bigger costs because of the confusion and misunderstanding outdated documentation can introduce.

4) At companies, culture is not necessarily supportive of documentation because of the immediate cost of documenting and maintaining docs. You can very well be punished for documenting things, and in doing so, may sacrifice meeting more important objectives. Even documenting things helps others in the company, if the company punishes you for it (and while perhaps rewarding others who profit from your docs), you're not being a hero or a martyr, feelings of moral superiority notwithstanding. You're being a fool. You're not doing charitable work at a company, after all.

5) "Duty" is a strong word. There is no general duty to document things. You can't just assert a duty exists by fiat, without establishing a basis for that duty. There are plenty of good things we can do, but are not duties.

Post reply on HN