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.

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.

I am continually cognizant of how many personal blogs I encounter that help me learn something I am curious about or solve a niche bug with which I have been struggling. I like to publish things I learn as I go to contribute back; if someone finds what I have written useful, I'm thrilled!

One thing at which I am trying to improve is to document personal coding challenges _as I go_ rather than documenting a finished state. I find it easier to write about something after it is complete rather than in the "messy middle" when I'm trying to come toward a solution. I'm trying to reflect more on the notion that documenting paths that one explored that went nowhere may be equally as valuable as the paths that went somewhere.

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 because they didn't anticipate anyone else taking over the project. Or maybe it was due to time constraint.

Anyway, I'm not documenting anything either. There's too much work.

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.

I've always liked Nadia's notes page: https://nadia.xyz/notes/

Seems like a low friction way to collect scraps of thoughts and ideas, put them out there without pretension, and then not worry about how many people are engaging or sharing. It's like your own Twitter-style page where you can riff without all the nonsense that comes from doing so on Twitter.

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

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

I also think, in some ways, someone who has just learned something is very well placed to educate others about it. There are arguments against that of course - someone who has just taught themselves about a topic may not be aware of the pitfalls or may only know how to do things in a sub-optimal way. But on the other hand, that person still remembers what it was like to not know anything about the topic so I think they can better communicate the basics to others who still don't know anything about it.

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!

I have a long text document where I put all ad hoc how-to related to the place where I spend half of my everyday life. For me only. Then I might migrate it to something more structured or share it with others. (But not the document itself. That’s a profanity-full/safe space.)

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

The older you get the more you realize that every popular piece of software got that way not because it was necessarily the best, but because it was the best documented. Often the tail wags the dog here as well. The software becomes better as it is documented.

Perhaps these days, more correctly framed as: "duty to feed proprietary AI's to enhance VC value and strengthen walled garden platforms" or some variation thereof.. I still have a knee-jerk reaction that information should be open and defeating walled gardens is best accomplished with more open data, but looking back at how much of the open web was just used to strengthen Google, FB, etc. I am.. concerned? AI chat bots are a very strong decoupler of platform users to data sources...

[edit to add] still generally like this piece and agreee with the intent. I have benefited greatly from all the information shared by people online..

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.

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

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.

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 is a waste of your time and others.

I would love to document everything in my wheelhouse if I could. Unfortunately I don’t have the time to do so due to unreasonable workloads and lack of staff/resources. I firmly believe in a work/life balance and have to cram everything into a 40 hour week. I constantly have to put out fires and treat everything like triage. The most important stuff is documented to the “T”.

I document in my workplace, and I love the idea of documenting things outside the workplace.

Inside the workplace, I find that people mostly don’t read documentation, but I write it anyway, because I tend to go back to it as a reference, and I can point others to it when they ask questions.

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.

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.

As a fellow blogger, I heartily agree.

Unfortunately, I am not as competent and blaze fewer trails.

Not a duty. More like a hobby.

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.

  - 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

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

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.

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.