[HN Gopher] Duty to Document (2023)
___________________________________________________________________
Duty to Document (2023)
Author : sarimkhalid
Score : 138 points
Date : 2024-01-05 13:22 UTC (9 hours ago)
(HTM) web link (nicolasbouliane.com)
(TXT) w3m dump (nicolasbouliane.com)
| snide wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| > 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 wrote:
| 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 wrote:
| 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 wrote:
| 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.
| mminer237 wrote:
| 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.
| zerojames wrote:
| 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.
| nicbou wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| Most enduring sofware is always those "one-off prototypes" that
| people cook up over a few days.
| avg_dev wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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
| giancarlostoro wrote:
| Especially as what you've documented becomes obsolete over
| time.
| pjc50 wrote:
| 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.
| nicbou wrote:
| I offer them a refund. It gets the point across.
| avgcorrection wrote:
| 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.
| paxys wrote:
| 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.
| judemelancon wrote:
| 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.
| zvmaz wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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)
| kstrauser wrote:
| 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.
| JackFr wrote:
| 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
| CrypticShift wrote:
| 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
| nicbou wrote:
| > 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 wrote:
| > 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 wrote:
| 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 wrote:
| 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.
| bad_username wrote:
| > After the duty to document, comes the duty to expose it
|
| And then to maintain it. Which is hard.
| gavinhoward wrote:
| As a fellow blogger, I heartily agree.
|
| Unfortunately, I am not as competent and blaze fewer trails.
| metabagel wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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/
| bad_username wrote:
| 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 wrote:
| 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.
| jrexilius wrote:
| 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 wrote:
| 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 wrote:
| 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_ wrote:
| 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.
| anatnom wrote:
| 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.
| jmole wrote:
| I think LLMs will quickly assume the role of fish-hander-
| outer, even if they aren't actually writing useful
| documentation themselves.
| verve_rat wrote:
| 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.
| jstanley wrote:
| The problem is that this sort of documentation is often
| incorrect, incomplete, or out of date, so people learn not to
| trust it.
| tivert wrote:
| > 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.
| dllthomas wrote:
| > 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.
| eschneider wrote:
| 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.
| pphysch wrote:
| 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.
| Min0taur wrote:
| 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 wrote:
| > 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.
| akira2501 wrote:
| 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.
___________________________________________________________________
(page generated 2024-01-05 23:02 UTC)