9 ms·

Duty to Document (2023)

148 points by sarimkx 3y ago

pphysch 3y ago
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.
snide 3y ago
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.
- pjc50 3y ago
  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.
  - tonyarkles 3y ago
    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.
Bluecobra 3y ago
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”.
NoboruWataya 3y ago
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.
- sodapopcan 3y ago
  > 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 :)
zerojames 3y ago
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.
bluGill 3y ago
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.
- NoboruWataya 3y ago
  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 3y ago
    [deleted]
- zerojames 3y ago
  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.
- mminer237 3y ago
  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.
- nicbou 3y ago
  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.
- andrewaylett 3y ago
  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.
zero-sharp 3y ago
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.
- 70rd 3y ago
  Most enduring sofware is always those "one-off prototypes" that people cook up over a few days.
avg_dev 3y ago
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.
- vitiral 3y ago
  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.
- lo_zamoyski 3y ago
  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.
- nicbou 3y ago
  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 https://nicolasbouliane.com/blog/playwright-timeouts
zvmaz 3y ago
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.
tikkun 3y ago
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!
xyzelement 3y ago
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.
- kstrauser 3y ago
  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.
  - xyzelement 3y ago
    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)
CrypticShift 3y ago
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 https://nicolasbouliane.com/projects/all-about-berlin
- nicbou 3y ago
  > 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.
  - sakjur 3y ago
    > 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?
    - nicbou 3y ago
      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.
  - CrypticShift 3y ago
    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.
gavinhoward 3y ago
As a fellow blogger, I heartily agree. Unfortunately, I am not as competent and blaze fewer trails.
metabagel 3y ago
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.
- SCNP 3y ago
  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)
avgcorrection 3y ago
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.)
jumpman500 3y ago
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.
- andrewjf 3y ago
  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'
- maxvt 3y ago
  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-infrastructure-as-code-and-now-youre-gonna-hear-about-it?slide=31 https://speakerdeck.com/maxvt/i-got-a-lot-of-problems-with-i... [2] https://documentation.divio.com/ https://documentation.divio.com/
- bad_username 3y ago
  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.
blueridge 3y ago
I've always liked Nadia's notes page: https://nadia.xyz/notes/ 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.
jrexilius 3y ago
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..
penguin_booze 3y ago
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.
- groby_b 3y ago
  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".
- tom_ 3y ago
  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.
deleted 3y ago
[deleted]
Min0taur 3y ago
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.”
simonw 3y ago
> 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 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.
akira2501 3y ago
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.
- justincredible 3y ago
  [dead]
julienreszka 3y ago
Not a duty. More like a hobby.

148 points by sarimkx 3y ago

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.

snide 3y ago

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.

pjc50 3y ago
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.
- tonyarkles 3y ago
  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.

Bluecobra 3y ago

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

NoboruWataya 3y ago

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.

sodapopcan 3y ago
> 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 :)

zerojames 3y ago

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.

bluGill 3y ago

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.

NoboruWataya 3y ago
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 3y ago
  [deleted]
zerojames 3y ago
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.
mminer237 3y ago
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.
nicbou 3y ago
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.
andrewaylett 3y ago
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.

zero-sharp 3y ago

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.

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

avg_dev 3y ago

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.

vitiral 3y ago
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.
lo_zamoyski 3y ago
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.
nicbou 3y ago
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 https://nicolasbouliane.com/blog/playwright-timeouts

zvmaz 3y ago

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.

tikkun 3y ago

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!

xyzelement 3y ago

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.

kstrauser 3y ago
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.
- xyzelement 3y ago
  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)

CrypticShift 3y ago

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 https://nicolasbouliane.com/projects/all-about-berlin

nicbou 3y ago
> 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.
- sakjur 3y ago
  > 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?
  - nicbou 3y ago
    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.
- CrypticShift 3y ago
  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.

gavinhoward 3y ago

As a fellow blogger, I heartily agree. Unfortunately, I am not as competent and blaze fewer trails.

metabagel 3y ago

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.

SCNP 3y ago
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)

avgcorrection 3y ago

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

jumpman500 3y ago

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.

andrewjf 3y ago
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'
maxvt 3y ago
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-infrastructure-as-code-and-now-youre-gonna-hear-about-it?slide=31 https://speakerdeck.com/maxvt/i-got-a-lot-of-problems-with-i... [2] https://documentation.divio.com/ https://documentation.divio.com/
bad_username 3y ago
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.

blueridge 3y ago

I've always liked Nadia's notes page: https://nadia.xyz/notes/ 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.

jrexilius 3y ago

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

penguin_booze 3y ago

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.

groby_b 3y ago
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".
tom_ 3y ago
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.

deleted 3y ago

[deleted]

Min0taur 3y ago

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

simonw 3y ago

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

akira2501 3y ago

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.

justincredible 3y ago
[dead]

julienreszka 3y ago

Not a duty. More like a hobby.