Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

The Opposite of Documentation is Superstition (2020)

buttondown.com

Post reply on HN
Print view View original

11–20 of 87 posts

Re: The Opposite of Documentation is Superstition (2020)

#11

Post by ChrisMarshallNY »

nox101 wrote: post #4

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

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/

Re: The Opposite of Documentation is Superstition (2020)

#12

Post by ChrisMarshallNY »

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.

Re: The Opposite of Documentation is Superstition (2020)

#13

Post by vincent-manis »

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.

Re: The Opposite of Documentation is Superstition (2020)

#14

Post by shizzy0 »

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.

Re: The Opposite of Documentation is Superstition (2020)

#15

Post by Animats »

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.

Re: The Opposite of Documentation is Superstition (2020)

#16

Post by w10-1 »

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.

Re: The Opposite of Documentation is Superstition (2020)

#17

Post by fiforpg »

Animats wrote: post #15

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…

> ritual-taboo programming

I like to think of it as "cargo-cult programming", along the lines of the well-known essay by Feynman.

Re: The Opposite of Documentation is Superstition (2020)

#18

Post by a_t48 »

vincent-manis wrote: post #13

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…

Thanks for the reminder to make the concepts section of my site easier to read. :)

Re: The Opposite of Documentation is Superstition (2020)

#19

Post by Animats »

fiforpg wrote: post #17
Animats wrote: post #15

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…

> ritual-taboo programming I like to think of it as "cargo-cult programming", along the lines of the well-known essay by Feynman.

Cargo cults don't work at all. Ritual-taboo systems sort of work but are suboptimal.

Re: The Opposite of Documentation is Superstition (2020)

#20

Post by IgorPartola »

Animats wrote: post #15

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…

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.

Post reply on HN