> 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.
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.
However, I wrote this post while thinking about easy fixes that are really hard to discover, such as this one yesterday: https://nicolasbouliane.com/blog/playwright-timeouts
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.
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.
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".
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.
…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
- they don’t incentivize good documentation
- they don’t set the expectation that “everybody writes”
- they don’t document themselves!
However, the "you can hand out a link" part is what really grinds my gears. The expectation of my former coworkers that it is <someone else>'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 <internal docs page> and search for <relevant term>.
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.
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.
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.
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.
Anyway, I'm not documenting anything either. There's too much work.
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.
"Documentation" in my mind does have an audience that you hope can benefit from what you are writing. The difference between that and journaling is that you need to define what this audience is like, their starting point and interest, and then write in a way that dovetails with that.
Maybe like this: journaling is an exploration that takes you from where you are to some hopefully elevated but not-known point. Documentation takes your reader from where they are to where you want them to get to.
Or like this: only you can assess the quality of journaling. Only your audience can assess the quality of your documentation.
(and I guess the audience can be yourself in the future. EG, I figured out the wiring schematic for my house and I am going to document it for myself in the future so I can get to this point of understanding quicker. But that still has an author-audience relationship, the future version of yourself might say "what the fuck was I thinking when I wrote this, this doesn't make any sense for my wiring needs" whereas that expectation wouldn't exist for a journal)
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.
- 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.
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.
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.
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 that in the US for booking tables at restaurants already?
And then to maintain it. Which is hard.
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.
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 :)
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'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.”
[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..
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.
Search is only one method through which someone can find what you write. I read a lot of personal websites that I found out about through friends, HN, and links from one site to another.
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.
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.
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.
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...
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.
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.
Unfortunately, I am not as competent and blaze fewer trails.