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.

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.

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.

https://wiki.lspace.org/Substition

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

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.

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.

Almost every human will do this for something IRL. As semi-irrational creatures, we tend to forcibly seek out patterns where there are none.

Some people become so encrusted with such behaviour that it legitimately impacts their ability to operate effectively in modern society.

Not surprisingly, the religiously-afflicted tend to pack the upper end of this spectrum.

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.

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!

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.

As in, the reason it isn't documented is that no one has a clue...

Literal interpretation of anecdotes lead to superstition.

Ironically this leads to them becoming documented.