[HN Gopher] The Opposite of Documentation is Superstition (2020)
___________________________________________________________________
The Opposite of Documentation is Superstition (2020)
Author : BerislavLopac
Score : 146 points
Date : 2024-11-27 08:32 UTC (4 days ago)
(HTM) web link (buttondown.com)
(TXT) w3m dump (buttondown.com)
| smitty1e wrote:
| I have also used the phrase "tribal knowledge" in the
| documentation-vacuum context.
| m348e912 wrote:
| There could be a business to be made in capturing and
| disseminating tribal knowledge for organizations. Even orgs
| with the best documentation don't have a great mechanism to
| capture and make available tribal knowledge which is un-
| authoritative, sometimes conflicting, and constantly changing.
|
| In the past I made an effort to address this by creating a
| unofficial but quickly searchable document repository
| documenting every question I have gotten from a teammate by
| either answering it or pointing to where the authoritative
| answer could be found.
|
| What I found was the following:
|
| 1. Questions are repetitive, you can quickly build a base of
| tribal knowledge and point people to the answer. 2. If the
| document tool is quick and efficient, team members will
| generally check it first instead of asking. 3. Sometimes
| document tribal knowledge conflicts with someone else's tribal
| knowledge. This is a great opportunity to hash out the more
| correct answer and update the document. 4. Tribal knowledge
| gets stale fast and needs constant curating. 5. The less
| friction to find an answer, eg fast access and fast/accurate
| searching, greatly increases success.
|
| NB. GPT is a perfect front end for such an effort.
| wjholden wrote:
| I would have loved to train an LLM on my old technical blog.
|
| In my last job, I used a blog to write informal reports. I
| set pretty loose rules for the blog for my team. We would
| post meeting minutes, outage postmortems, scripts, tricky
| one-liners, general lessons learned, and so on. We used
| SharePoint, which is kinda meh but it works. The "Alert Me"
| feature in SharePoint made it easy to subscribe my teammates
| to the blog via email, so you got the benefits of email (push
| notifications) without the drawbacks (employee mailboxes are
| unsearchable once they leave).
|
| I believe email contributes to this tacit ("tribal")
| knowledge that the OP names. I think my blog went a long way
| to counter this effect. A major goal in our blog posts was to
| capture the "why" behind our decisions. Often, we fail to
| remember the nuances of our own decisions in hindsight. I
| always thought it was important to name our present
| priorities and known-unknowns.
| worksonmymach wrote:
| Atlassian Rovo is this.
|
| The trick is to get people to get their tribal knowledge down
| in public Slack channels or their docs system.
|
| Recording most Zooms with AI summaries may help.
| drewcoo wrote:
| If the businesses valued it, it would be documented
| knowledge. It's clearly not worth the time or money to
| document.
|
| If the workers values it, it would likely be documented
| knowledge. Undocumented knowledge can be job security.
| m348e912 wrote:
| > If the workers values it, it would likely be documented
| knowledge. Undocumented knowledge can be job security.
|
| You're mostly right. It's paradoxical in some ways. Workers
| generally won't go through the trouble of documenting
| tribal knowledge. However they greatly appreciate if
| someone else does.
| worksonmymach wrote:
| Hard to avoid some tribal knowledge. To be free of it you need
| full reference documentation and tutorials for everything you
| do. And to update it as you go. And to realize what might be
| missing from a paedagogical perspective. Not easy and probably
| not possible for a commercial operation. And not necessary.
| 80-20 rule applies.
| smitty1e wrote:
| And applying that 80/20 rule implies a culture of writing
| things down and communicating them, which doesn't scale and
| is highly dependent upon the general chattiness of the team
| in question.
| nox101 wrote:
| Seems to me documentation can also be superstition if it's out of
| date.
|
| I wonder if LLMs can generate docs at any reasonable level of
| usefulness and accuracy
|
| Speaking of which, I just tried using ChatGPT to create a React
| app with typescript and rollup. What it generated didn't work
| (got errors). Of course I could tell it the errors and it fixed
| them but it suggests they aren't yet ready to write accurate docs
| iterateoften wrote:
| Maybe LLMs make docs irrelevant if they are just generating
| static pages or doc strings. Why spend the time generating
| something static when everyone has their own LLMs they can just
| ask directly? Anything you can generate as docs someone can
| generate themselves anyways.
| danihh wrote:
| We actually ran this train of thought with our startup right
| now. The problem? Not everybody knows what questions to ask.
| For non-power users it's usually better to present digestible
| information and create docs that answer questions they didn't
| even know they had.
| blharr wrote:
| I mean, LLMs can be regenerated as needed. With every major
| release, you might regenerate the documentation. Then, you
| don't need to have everyone taking time to ask the same
| questions, reducing the amount of times you need to call the
| LLM. And thereby you can use a more expensive LLM, like o1 to
| generate the documentation where you wouldn't want to use it
| normally
| pona-a wrote:
| The thing is, good documentation captures the difference
| between what you expect and what something is. LLMs, as they
| exist now, are mass-producers of cliche. You can sense it
| even in their prose or those inverted puzzle evaluations [0]
| , they are simply statistical models picking the most likely
| options without enough depth to subvert the average. When you
| ask them to describe a piece of code, you'll only get the
| rephrasing of what the code already says.
|
| - [0] https://github.com/cpldcpu/MisguidedAttention
| AshamedCaptain wrote:
| Why would you bring ML up? The entire example problem brought
| up by TFA is because the ink-to-shape transform likely uses
| some ML behind the scenes (plain interpolation likely) , and as
| consequence, it is an _indocumentable_ blackbox even if you
| wanted to document it. Superstition is the only way you can
| make it work.
|
| In fact, "superstition" very neatly defines most prompt
| engineering for LLMs.
| VectorLock wrote:
| >In fact, "superstition" very neatly defines most prompt
| engineering for LLMs.
|
| Its weirdly fascinating how this is developing. Like some
| people boldly claiming that if you offer to tip your LLM it
| does better. And if you say things like "Think hard and check
| your work" it gives more accurate results.
| ChrisMarshallNY wrote:
| I tend to use in-code documentation[0].
|
| Works pretty well. Could still [theoretically] go out of date,
| but that hasn't happened, so far.
|
| The one thing that does happen, though, is copy/pasta errors.
| I'll copy a bunch of code, including the headerdocs, and paste,
| but forget to adjust the docs.
|
| [0] https://littlegreenviper.com/leaving-a-legacy/
| pasc1878 wrote:
| But it covers only how to use a function if you know what the
| system is meant to do or know which function to call in the
| first place.
|
| You need some overalls documentation to explain the concepts
| and how to put things together. When the user understands
| that you can use in-code documentation but even then only if
| you need to use one function at a time - there needs an
| explanation of how to put things together.
| ChrisMarshallNY wrote:
| That's what I use the README for.
|
| With Apple's docc, you can drop READMEs throughout the
| system, and they show up in Xcode's doc browser (and can be
| referenced from the code).
| eddd-ddde wrote:
| Integration tests? They show how the system works as a
| whole, and they don't go out of date.
| ChrisMarshallNY wrote:
| They are, indeed, useful.
|
| I usually create full-fat test harnesses[0] for my stuff,
| as that gives a totally realistic implementation example.
|
| But I think having a well-written README is more likely
| to be useful.
|
| API/implementation documentation (whether docs or tests),
| are much more likely to be read, than end-user docs.
|
| [0] https://littlegreenviper.com/testing-harness-vs-unit/
| martin-t wrote:
| I inherited 100k LoC "documented" by an LLM.
|
| LLMs can put into words what a programmer can infer from struct
| definitions, function signatures, names and even taking a
| cursory look at a function body.
|
| LLMs cannot retroactively find out the _why_ of design choices.
| If you don't document the reasons behind decisions while making
| them, they'll be lost, which is exactly what leads to
| superstition. As a result, changing code is error prone because
| you never know when code is written in a particular way for a
| good (and still valid) reason or just because.
| ValentinA23 wrote:
| Related: Show HN: Auto Wiki - Turn your codebase into a Wiki
|
| https://news.ycombinator.com/item?id=38915999
| VectorLock wrote:
| Someone at work recently introduced a thing that would create
| git commit messages from code, completely negating the
| necessity of the programmer to provide accurate not-
| contained-in-code context. If they weren't across an ocean I
| would have shook them by the shoulders until they understood.
| onemoresoop wrote:
| > I wonder if LLMs can generate docs at any reasonable level of
| usefulness and accurate
|
| A lot of times documentation isn't read by anyone for stretches
| of time till it's needed. I imagine documentation by LLMs will
| make the situation worse if nobody verifies its corectness. I
| don't believe in magic solution, good documentation that is not
| out of date requires work and if a company doesn't allocate
| resources no magic will fill in the gaps.
| closed wrote:
| This is an interesting case, since the pigeon study is about what
| happens when the underlying process is random.
|
| But if the shape drawing process isn't random, I think the
| author's experience of feeling unable to articulate the rules AND
| gravitating to a set of behaviors is a good example of procedural
| memory (implicit vs explicit).
|
| Explicit rules would probably help speed things up, though!
| ChrisMarshallNY wrote:
| He's really talking about the user's mental model, here.
|
| I've found that it is sometimes a good idea to reinforce mental
| models that don't actually reflect the operation of the software
| (in my case) under it.
|
| Documentation is good, but, in my experience, almost no one ever
| reads it. I can tell, because of all the questions that I get,
| that are in the docs.
|
| That's totally my fault. A really good tech writer could probably
| do a better job of conveying information.
|
| That said, I think that it's important to present good,
| discoverable UI, that doesn't punish users for exploring.
| pfix wrote:
| Both is important. And related. Documentation needs to be
| discoverable. I was amazed when I tried jj (jujutsu, the "new
| git") and it popped me into some kind of weird textual user
| interface after executing `jj split` and I felt lost. I
| guessed, pressing `?` won't hurt and it told me just to use the
| mouse. The menues showed the related hot keys.
|
| But the actual documentation of the tool has room for
| improvement. I needed a YouTube video to get started and that's
| rare for me.
|
| So what I want to say is, that you need an intuitive,
| discoverable UI, but also a documentation that has each case
| (and if it's just for linking in 1st level support cases) _and_
| is discoverable. And by that I mean both easy to grasp (e.g.
| following https://diataxis.fr/) and also can actually be found.
| I've had cases where a tool had good documentation, but
| actually finding it was the hard part.
| throwaway14356 wrote:
| our architects love building the house before making the
| drawings. i imagine we will probably figure it out eventually
| when the feature set can be strictly defined.
|
| (maybe you eventually want a bath tub and a toilet in each
| room? maybe not?)
| ChrisMarshallNY wrote:
| I wouldn't call it "love," more than "necessity."
|
| It really depends on the nature of the project, but UI
| design often requires a lot of "Paving the Bare Spots"[0].
| It's really just too damn complex and counter-intuitive (or
| too intuitive) to catch in Requirements.
|
| Software allows us to iterate this incredibly quickly.
| Hardware design also does it, but at a _much_ slower pace,
| and a _much_ greater cost.
|
| [0] https://littlegreenviper.com/the-road-most-traveled-
| by/#pavi...
| toast0 wrote:
| I've got architectural plans for my house. Parts of them
| are useful, but most of it isn't because the house doesn't
| match the plans. The details on the plans for the parts
| that match aren't trustworthy, because of all the parts
| that don't match. This is a relatively new construction,
| with minimal remodeling; it's just as they were building,
| they decided to do something else, and not update the
| drawings.
|
| This is different than commercial work where in addition to
| the original plans, you also get as-builts, which can be
| expected to be accurate, and are expected to be updated.
|
| If you only want to document once, it makes sense to do it
| once the thing is built, rather than before, because
| there's a good chance the actual thing will be different
| than the plan. If you will update it, it might make sense
| to start documentation before the thing is built.
|
| Of course, if you never get around to writing
| documentation, it never needs to be updated.
| vincent-manis wrote:
| I can't remember the number of times I have given up on software
| because there is no "Concepts and Facilities" document that gives
| me a mental model of what the program will do and how I operate
| it. Instead, one sees a website with a mass of unrelated
| documents that I'm supposed to read in some order, and divine how
| everything works.
|
| Maybe because I'm a child of the 20th century that I value
| documentation that gives me a path from understanding what and
| why to learning how I can use it, with a master index so I can
| look up exactly what the "Mung Until No Good" command does, and
| see which other commands relate to it.
|
| Perhaps one day generative AI will be good enough that we can
| feed in one of these websites, with its pages with titles like
| "Migrating from V4.7.2 to V4.7.3" and "Building for OS/2 Warp" (I
| exaggerate, but only slightly) to documentation that is useful
| for learning, use, and troubleshooting. I live in hope.
| a_t48 wrote:
| Thanks for the reminder to make the concepts section of my site
| easier to read. :)
| floating-io wrote:
| Not just an issue for documentation, but also for marketing
| materials. I can't count the number of times I've looked into
| some app that was referenced vaguely in a comment somewhere,
| only to have to dig for half an hour on that thing's web site
| just to figure out what the thing is supposed to even do in the
| first place...
| shizzy0 wrote:
| Some of the best technical documentation I've ever written has
| straight up lies in it. Granted they were placed there in the
| service of distilling the most germane portions of the API I was
| trying to explain. But it made a huge difference once I decided
| my code in the library didn't have to be my code in its
| documentation. I felt a little like a biographical writer who
| makes a composite character. But honestly I recommend trying it.
| Lie in your docs if it serves the greater goal of communicating
| what's most important. Let the computer labor in the "truth" and
| its tediums.
| Noumenon72 wrote:
| Do you mean you just left out required args, try-catches for
| checked exceptions, and so on, so the example would be easier
| to read? Did you put an asterisk on, like "* illustrative code:
| will not compile"?
| Animats wrote:
| I've called this ritual-taboo programming for decades. It happens
| for user interfaces and APIs when the documentation is absent, or
| only consists of examples. If there's no reference documentation,
| everything is a copy of something someone else did. Nobody
| understands how it really works.
|
| Now, for some interfaces, this isn't too bad. Most people don't
| know why US AC power plugs are polarized, or what the ground
| prong is for. Electricians have to, but users do not.
|
| For more complex interfaces, it means that many functions will
| either be misused or undiscovered. This is the source of the
| plaint that only 10%-20% of a product's features are used.
|
| On user interface design, the classic is "Tog on Interface",
| Bruce "Tog" Tognazzini, 1992. That's from the Mac UI era. A more
| modern take is "The Gamer's Brain", by Celia Hodent, designer of
| Fortnite's UX.
|
| Software internal documentation seems to suffer today from a
| mindset that comments are unnecessary and waste space. Especially
| in the Javascript era. It's worst in languages that don't have
| data declarations. There's no place to properly document the
| data.
|
| Rust has good conventions and tools for documenting data. There's
| a well defined place where the documentation for each structure
| and field goes, and reasonable tools for checking it and turning
| that into documentation. If you fail to do this, when you publish
| your crate on crates.io, the documentation pages will come up
| blank, which screams "loser".
|
| Rust is weak on function parameter documentation. There should
| have been a defined place where each formal parameter gets a
| comment, which then appears in the documentation of the call.
|
| Most other languages don't take such a hard line. More should.
| fiforpg wrote:
| > ritual-taboo programming
|
| I like to think of it as "cargo-cult programming", along the
| lines of the well-known essay by Feynman.
| Animats wrote:
| Cargo cults don't work at all. Ritual-taboo systems sort of
| work but are suboptimal.
| michaelcampbell wrote:
| Only if that's how you make the distinction between the 2.
| Copying something hoping it will do something you want
| because it did do that thing elsewhere, without
| understanding at all how or why it works is essentially the
| definition of CC programming.
| andrewflnr wrote:
| Honestly not a bad delineation, considering what the
| original/actual "cargo cults" were.
| IgorPartola wrote:
| How do you view self-documenting interfaces?
|
| Have you ever read the manual for your browser which you are
| using to make this comment? The OS on which the browser is
| running? The device on which they are running?
|
| I think there are interfaces that need to be usable assuming
| documentation will not be read. These are of course user
| interfaces, not necessarily APIs. But if you are creating
| something like a library of basic math functions I would rather
| read your code than your docs.
|
| Some of the worst docs I've read lately have been for ffmpeg
| and mp4box. The former sometimes straight up has things like
| "so one guy tried this and it worked for him so we recommend
| you try it and see how it works for you". The latter has like 4
| examples with no explanation of what you are looking at or how
| to make anything else work. The project used Stack Overflow for
| their docs because nobody can really figure out what to do with
| it right away. I'd rather take readable code in this case over
| the terrible docs.
| throwaway14356 wrote:
| writing great documentation is extremely hard. sometimes it
| is so well done you only notice it in how fast and easy you
| progress. the funniest opposite was documentation i wrote
| myself but turned out to complicated for the future self. i
| kept thinking, what is this guy on about?? it assumed the
| reader knew all kinds of things i didn't and it made effort
| to explain the obvious.
| lelandbatey wrote:
| > How do you view self-documenting interfaces?
|
| > Have you ever read the manual for your browser which you
| are using to make this comment? The OS on which the browser
| is running? The device on which they are running?
|
| Have you ever read the manual for the tools used to build the
| building that you live in? A manual for the trowels, tape,
| mud, and drywall that built and makes up your walls? Or a
| manual for the Romex in those walls? A manual for the
| concrete foundation of your building?
|
| No? That's because using/depending on those things doesn't
| require nearly anything of you; you stand on the floors and
| lean on the walls without thought.
|
| You browse the web _constantly_ , so you do it without
| thought. Not so with your taxes, despite their similar
| constance and ubiquity, because they are not constant and
| thus haven't had the same abstractions engineered into their
| very DNA.
|
| But even things like buildings/floors/doors with that level
| of "no need to think about them" only afford that to you
| based onto their frequent use. Few other pieces of software
| afford that same consistency. With time though, they will. I
| think we'll see a lot of software grow to be everore of a
| "skin round a spreadsheet", especially as we comoditize the
| few remaining frontiers of UX design (e.g. mobile devices) in
| the same way as desktop design has converged on common
| patterns like the chat-log-and-history, the search bar, the
| photo gallery, the text editor, and the spreadsheet.
| yearolinuxdsktp wrote:
| What are you talking about with taxes? They have quite a
| few abstractions in them---capital gains income,
| dependents, just to name two.
|
| I am laughing at 'remaining frontiers' of UX design. This
| year for Christmas I wish for mobile devices with browsers
| that don't crash and lose my form entry. This year, I wish
| for YouTube that doesn't find new ways to turn on autoplay
| (TV queue being the latest one I had to turn off, despite
| having already turned off AutoPlay on that device in
| settings... each of my devices has autoplay turned off...
| yet TV queue came with autoplay turned on... crooked
| YouTube!) But sadly, this kind of thing is not what the
| state AGs are looking at---but to me, the constant
| bypassing of disabled AutoPlay is anti-consumer AF and must
| be stopped. That is the remaining frontier.
| fao_ wrote:
| > You browse the web constantly, so you do it without
| thought. Not so with your taxes, despite their similar
| constance and ubiquity, because they are not constant and
| thus haven't had the same abstractions engineered into
| their very DNA.
|
| In the UK, the government automatically takes tax out of my
| income and tax is indicated as part of my pay cheque. It
| requires absolutely no thought from me.
| sahmeepee wrote:
| > Have you ever read the manual for your browser which you
| are using to make this comment? The OS on which the browser
| is running?
|
| For niche situations, yes, e.g. different browsers having
| different keyboard shortcuts for hard refresh. It's quite
| common for people to assume they know how to do it in one
| browser because they knew the shortcut in another, but when
| they just get a normal refresh they don't realise their
| error.
|
| Software written to be used by billions of people per day
| must be written to have a very low barrier to entry, and even
| if it contains sophisticated and complex features they must
| not be essential for >99.99% of the software's overall usage.
|
| The downside of this approach is that many people never learn
| about features in everyday software that would make them much
| more productive. Keyboard shortcuts as above are the classic
| example and are almost always documented, but there are many
| more unexplored features and not all requiring significant
| memory or technical skill to make use of. I've not heard of a
| regular office job in the last 15 years where there would be
| induction training on the core tools (OS, browser, office
| suite). It's assumed that you're not employable if you don't
| know how to use them, and by implication that knowing how to
| use them is a binary thing rather than a spectrum.
| brabel wrote:
| > But if you are creating something like a library of basic
| math functions I would rather read your code than your docs.
|
| Talking about software specifically: this is the exact wrong
| way to do it. A programming interface should be easy to use
| and "self-documented" to some extent (by, e.g. using the type
| system as much as possible to make bad states
| unrepresentable), but only very simple interfaces are usable
| that way. For most real-world interfaces, there's just no way
| you can encode all the "rules" in the type system and the
| names. You absolutely need to document how your interface
| works in general, what each part is used for and expected to
| do, special cases and so on that are just impossible to know
| otherwise. Now, if you just read the implementation instead
| (and notice that you would need to read all implementations,
| most interfaces are likely implemented in many different
| ways) you're not coding against an interface at all. You're
| assuming the implementation is the interface. You're ignoring
| what the implementer intended to be private and subject to
| change. Don't do that.
| jajko wrote:
| Yeah thats a horrible approach that creates massive
| additional costs down the line, usually not author's
| problem anymore though.
|
| Can't really put finger on it precisely, maybe its too
| large ego (my time is too valuable for some pesky
| documentation for idiots, I am a superstar! No you're not,
| you are at vee best a brilliant junior...).
|
| Or maybe lack of basic empathy, surprisingly high number of
| humans can over time learn how to work in society but any
| novel situation requiring some empathy they handle like
| mammoth ina porcelaine shop.
|
| Or something else in similar vein. That was quite shocking,
| entering adulthood and discovering vast number of folks
| have such issues
| dingnuts wrote:
| I used to write a lot of comments and I don't much
| anymore.
|
| Usually a long comment is a smell. If the way something
| works isn't obvious and must be explained, it can
| probably be better designed.
|
| Code changes and then comments have to be updated, and
| often aren't. If they aren't just wrong, the context is
| often so changed that they aren't useful. You wind up
| reading the legacy code anyway, and you and the author
| both wasted time with comments.
|
| My team is smart and competent. I need them to read the
| code to make sure their changes are safe, anyway. They do
| not need their hands held. They don't need me to waste
| time writing comments that will soon be outdated, or that
| explain something I should have designed better.
|
| Finally, management doesn't apply an OKR to intangible
| code metrics like internal documentation. Should they? I
| don't know, but it's their code, not mine, so I'll write
| it to the standard they apply.
|
| These are the reasons you have to work in code that is
| poorly documented. It has nothing to do with a lack of
| empathy -- if I were to allow my employer to extract
| extra value from me by using my empathy for my teammates
| as a lever that would be exploitation. If I spend more
| time on documentation -- which the employer doesn't value
| -- instead of functionality, I'll be punished at review
| time for wasting time on worthless things.
|
| Maybe you should stop letting your company manipulate you
| into doing more work than they're paying for. If they
| value internal documentation, they'll create an OKR or
| KPI or whatever to make sure you're paid to do it.
| Otherwise it's unpaid labor for a for profit corporation.
| I'm not doing that. Are you?
| danielheath wrote:
| It's not that I'll assume the internals are not going to
| change.
|
| I just don't trust the docs to be accurate anymore. The
| implementation contains an accurate description of what
| it actually does.
|
| I still read the docs... with a grain of salt.
| jajko wrote:
| Man, sometimes I would give some gold for some
| documentation, even 10 years old. Half-irrelevant,
| doesn't matter. At least something. Sometimes, I don't
| have even that. That's what drowning in complexity looks
| like since there are some many question marks and often
| nobody anymore to answer them.
|
| Even stellar code just tells me whats going on. Doesn't
| tell anything about why its happening, what consequences
| does it have in other systems, what are the overall
| constraints of this domain etc.
|
| I agree generally too long comments aren't best, or even
| just non-flexible rules. But denser the logic is, the
| more spread its across multiple systems and environments,
| the more info the better.
|
| And to be changing some dense code and completely
| ignoring comments just next to it describing them...
| that's just rude to be polite. Shows who is a team player
| and who isn't. Trust me, if you want to make friends and
| have some respect in some long term team, this is one
| sure way how to do it.
| tempodox wrote:
| It's always the same problem: The work generated by doing
| documentation, including the possible need for specialized
| talent, is quite directly perceivable. The work generated by
| the absence of documentation is more under the radar and
| disguised as "cost of doing business", which makes it harder to
| convince the anti-documentation crowd. Not to mention the "job
| security" aspect of everything being in the heads of the ICs.
| hiAndrewQuinn wrote:
| In other words, it's a principal-agent problem. The ICs
| (agents) tasked with creating documentation see it as extra
| work with no immediate payoff for them, and indeed even some
| long term downsides; the org (principal) bears the hidden
| costs of its absence - inefficiency, delays, trouble when Mr
| Magic Touch switches jobs. There's nothing special in kind
| about this, it happens in all industries.
|
| The fix? Stop leaving it optional. Tie documentation to
| performance reviews, bake it into deliverables, reward teams
| for knowledge-sharing. If you can't convince them with logic,
| align incentives so ICs can't ignore it. It's either that, or
| accept that you believe ICs have better things to do with
| their time. But make a conscious choice either way, I'm
| begging you!
| onemoresoop wrote:
| Forced documentation by ICs could be poorly written, leave
| things out or quickly sync out of date. I think there
| should be a dedicated team tasked with managing this
| documentation.
| hiAndrewQuinn wrote:
| So long as you have the budget to hire for that, the
| world is your oyster. Alternatively you could take the
| risk and pass the savings on to the consumer - it's all
| up to you, my friend.
| sakex wrote:
| I agree to some extent, but I'd say it depends on the
| programming language. For instance, in Python, you absolutely
| need documentation because you don't know what type is
| expected, what different values can be passed or even the
| optional kwargs etc. It's also very common to pass strings as
| parameters when one should be using enums, which means you
| can't know what are the possible values without having the doc
| or diving into the code.
|
| In Rust however you can get away with way less documentation
| because the type system and signatures are self explanatory.
| And if you're doing things right, the set of values you can
| pass to your function is limited.
| tremon wrote:
| On the other hand, with Rust and Haskell you absolutely need
| type constructors to be easily discoverable. If open gives me
| an Fd, but the library function accepts a Stream, I shouldn't
| need to spend hours wading through sparse documentation to
| find how to convert between the two.
|
| Something like Hoogle becomes a necessity if you want your
| type system to replace the need for documentation.
| makeitdouble wrote:
| These are all valid point if documentation is the only way to
| get the info.
|
| They key point to me in TFA: "The feature is a black box"
|
| This doesn't apply to software internal documentation. It's not
| a black box and you can give any deep you want to know what is
| and isn't implemented, what has explicit tests and who wrote
| it.
|
| Whether comments on those are a waste of time of not will come
| down to how long it will take to write useful comments, how
| long it will take for the reader to understand the
| class/function/method otherwise, how much maintenance will
| happen on the comment itself after it's written, what it will
| cost when it will "rot", and what else (e.g. tests ?) the dev
| could do with all that time.
| mejutoco wrote:
| > Especially in the Javascript era. It's worst in languages
| that don't have data declarations. There's no place to properly
| document the data.
|
| Typescript is very common too. It has all the types needed to
| document the data. And vscode understands all the references
| and navigates through them by default.
| crazygringo wrote:
| > _For more complex interfaces, it means that many functions
| will either be misused or undiscovered. This is the source of
| the plaint that only 10%-20% of a product 's features are
| used._
|
| That's not a complaint, it's an observation, and it's not due
| to discoverability. It's because products are made for many
| kinds of users with many kinds of needs, and their needs often
| don't overlap a ton.
|
| I probably don't use 99% of what ffmpeg can do, but it does
| everything _I_ need it to. And with word processors it 's still
| the same principle -- I've never in my life needed to do a mail
| merge, or apply a watermark, or 100 other things. But other
| people do. And it has nothing to do with discoverability.
| w10-1 wrote:
| The opposite of docs is also expertise: learn through experience,
| then have a career moat. It's why Microsoft and Apple get away
| with secret API, which also gives them some leverage. Docs tend
| to be good only in the post-prototype, pre-dominance phase of
| rapid growth. Or when the author cares about users.
| throwaway14356 wrote:
| the fun of that study is that the pigeon behavior they think is
| to get food is superstition it self.
| GuB-42 wrote:
| One also could say that the opposite of open source is
| superstition.
|
| It works with the example given in the article: OneNote is
| proprietary software, and it is documented, though incompletely.
| Had it been open source, one could see exactly how shape
| recognition works, bugs, quirks and all. No documentation will
| give that amount of detail.
|
| Sure, not everyone has the time and skills for that, but maybe
| someone on stackoverflow does and have answered the question
| _with proof_ , that is, not a superstition.
| ozim wrote:
| Well one note is one thing - other thing is using open source
| libraries by devs.
|
| No one has time to read the code in depth so it is also mostly
| reading tea leaves like ,,oh it has a lot of stars and a lot of
| downloads so it must be good".
|
| Don't get me started on left pad ;)
| codr7 wrote:
| Isn't this more likely an example of LLM-crappification?
|
| As in, the reason it isn't documented is that no one has a
| clue...
| brabel wrote:
| In that case, it should be documented at least that the process
| is driven by LLM and hence, it's not known exactly how it makes
| a decision...but I guess that would not look good to most users
| so they just leave it out.
| codr7 wrote:
| Writing that you don't have a clue why the software works or
| doesn't isn't very good marketing :)
|
| Welcome to the stupid singularity.
| akira2501 wrote:
| Technically the opposite of documentation is anecdote.
|
| Literal interpretation of anecdotes lead to superstition.
|
| Ironically this leads to them becoming documented.
| ChrisMarshallNY wrote:
| Right now, I'm working on a SwiftUI project that displays charts
| of various statistics for our app system.
|
| The docs for SwiftUI are ... _less than ideal_.
|
| I'm pretty sure that it can do what I need, but the docs don't
| cover it _at all_. I 'll need to keep playing with code
| completion (which kinda sucks, right now, because Xcode keeps
| making up nonexistent APIs), and looking at the actual system
| exported headers.
|
| I'll get it, eventually, but this is pretty crazy bad.
| worksonmymach wrote:
| This refers to user docs rather than your team's README.md.
|
| Programmers have the luxury of documenting the previously
| undocumented for their repos (assuming management allocates
| time).
|
| End users would need to reverse engineer but that assumes
| predictability. Without that you get superstition as per article.
| bruce511 wrote:
| "Superstition" results from any number of things.
|
| A) insufficient docs B) programmer can't be bothered to read the
| docs C) programmer doesn't trust the docs D) programmer had a bug
| once, blames the underlying library, not his code E) programmer
| had a bug, changes code, bug goes away, jumps to conclusion.
|
| Trust in the docs is a big thing. If the docs are wrong a lot the
| the programmer is skeptical even when they're right.
|
| But I've also noticed that most developers simply don't read
| them. "I'm too busy (fixing bugs) to read the docs." Or "my
| backlog is so long I don't have time to learn how to do it right,
| I just want it done fast "
|
| Superstition occurs with the absence of knowledge - the existence
| of docs is necessary, but not sufficient, in overcoming that
| absence.
| drewcoo wrote:
| Superstition plus documentation equals religion.
| marmaduke wrote:
| The pigeon experiment is a great one to learn from not just about
| programming or software, but about life in general. Where are you
| getting your next dopamine hit? Is it random? Maybe that's where
| our idiosyncrasies come from.
| gmd63 wrote:
| Functionality doesn't exist if it's not communicated, whether
| through intuitive UI or documentation. Much like laws don't exist
| if they're not enforced.
| slwvx wrote:
| "Substition is the Discworld opposite of superstition.
| Superstition being the belief in the things that everyone
| believes in, but which are not true. Substition is the belief in
| things which are true but most people do not believe in."
|
| https://wiki.lspace.org/Substition
___________________________________________________________________
(page generated 2024-12-01 23:01 UTC)