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.)
Duty to Document (2023)
31–40 of 70 posts
Re: Duty to Document (2023)
#32I 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.
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)
Re: Duty to Document (2023)
#33The 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.
Re: Duty to Document (2023)
#34I’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 c…
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.
Re: Duty to Document (2023)
#35The 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…
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'
Re: Duty to Document (2023)
#36I'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.
Re: Duty to Document (2023)
#37The 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.
Re: Duty to Document (2023)
#38After 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…
> 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.
> 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?
Re: Duty to Document (2023)
#39I’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 c…
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)
Re: Duty to Document (2023)
#40Perhaps 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..