Duty to Document (2023)(nicolasbouliane.com)
nicolasbouliane.com
Duty to Document (2023)
https://nicolasbouliane.com/blog/duty-to-document
69 comments
The worst cost of documentation is that it often generates extra work for you in terms of complaints and updates. Not always reasonable ones, either. More than a few personal projects have been taken offline because it's too demoralizing to give things away and get negativity back.
I offer them a refund. It gets the point across.
Considering that some blog post about something can remain relevant for years—as opposed to some off-hand tip given verbally—, it is definitely difficult to just share knowledge in a way that cost you next to nothing. You could give some great advice that works now. But doesn’t in two years. And then it might be counter-productive.
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.
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.
Author here. Tell me about it! I'm documenting things for a living. There aren't enough hours in the day to write everything down.
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
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
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.
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.
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.
Especially as what you've documented becomes obsolete over time.
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.
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.
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".
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.
> 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.
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.
> The problem is…
…multifaceted from my experience.
1. At the org-level…
…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!
The worst environment is when people don't bother to update documentation. That's when you know you have a garbage shop.
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 <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.
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.
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.
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.
I think LLMs will quickly assume the role of fish-hander-outer, even if they aren't actually writing useful documentation themselves.
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.
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.
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.
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.
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.
Anyway, I'm not documenting anything either. There's too much work.
Most enduring sofware is always those "one-off prototypes" that people cook up over a few days.
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.
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.
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
https://en.wikipedia.org/wiki/Confessions_(Augustine)
https://en.wikipedia.org/wiki/The_Seven_Storey_Mountain
These are great suggestions. Thank you!
That's exactly the sort of thing I document for myself. Getting my thoughts together enough to explain them to a hypothetical, likely-nonexistent reader gives me a lot of clarity into my own thinking.
I call that "journaling" - I have a lot of physical paper journals that I wouldn't expect anyone to read - they so far have been write-only as a way to explore or clarify a topic for myself. I say "so far" because potentially I could read through them for valuable ideas that can be re-shaped for an audience.
"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)
"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)
That's such a blurry line, isn't it? And there are so many approaches. I tend to journal such things in the form of personal wiki pages documenting both my thoughts and why I think them, with links to sources. Basically, I'm writing to myself, but in a way that I could restore state after getting amnesia. It's probably overkill but it helps me think things through.
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.
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
- 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
> 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.
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.
In a sense, we may have less need to create "formal, structured documents." Even today, many companies archive a large part of their informal conversations (meetings, emails, Slack...) in addition to "memos" and other short docs. The LLMs may get their data from there. Imagining a future where even open everyday conversation is recorded is a privacy nightmare, so this may not always be possible in less digitized environments (immigrants assistance ? I don't know)
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.
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.
> 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 that in the US for booking tables at restaurants already?
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?
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.
> After the duty to document, comes the duty to expose it
And then to maintain it. Which is hard.
And then to maintain it. Which is hard.
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.
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.
> 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 :)
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 :)
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!
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.”
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.
Hardly. I'm not sure the average user has ever read a piece of iOS documentation. Many people, users and developers, prefer the interface to be the explanation. And software popularity is driven by all sorts of factors.
On the other side... I will take the iOS Swift documentation over the Android documentation any day of the week. It's not perfect but it's some of the best API documentation I've encountered over the last 20 years.
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..
[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.
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.
I recommend writing on your personal website! You will own your content and you can design the site and the user experience as you want.
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.
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.
I put my stuff on my own website, despite my analytics saying I get next to no traffic. It's not a waste of time, because the largest benefit accrues to me when I write it. And if no-one reads it then hopefully I can avoid being over-pretentious while still having something to link folk to if any of my random thoughts ever become relevant.
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.
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.
Codidact, Stack Overflow, or your own blog are all good options. In my experience plenty of problems are niche enough to rank highly in Google for the few people searching for them.
I'm a bit biased because my website has been around for a while and gets a fair amount of traffic. If you're going to create a digital garden, you better own the turf it's on. I have zero faith in other platforms treating its creators well.
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]
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.
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.
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.
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.
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/
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/
Completely agreed. Most documentation, for this reason, is basically useless because it's just wrong enough to be completely misleading and outdated virtually immediately. It takes a massive amount of investment into documenting internal stuff, just don't do it. Write clearer code, use commit messages as to the 'why'
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.
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.
This is what I do. I don't write docs for other people, I write them for myself. I find them most useful for processes that are intricate but that I won't have need to do for months at a time. (Looking at you, server certs)
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.
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.
Unfortunately, I am not as competent and blaze fewer trails.
Not a duty.
More like a hobby.
[deleted]
> 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.