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.

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.

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.

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.

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.

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.

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!

Literal interpretation of anecdotes lead to superstition.

Ironically this leads to them becoming documented.

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