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

81–87 of 87 posts

Re: The Opposite of Documentation is Superstition (2020)

#81

Post by IgorPartola »

lelandbatey wrote: post #42
IgorPartola wrote: post #20

Earlier quoted context omitted.

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 basi…

> 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 t…

Ironically, I have read parts of the international building code when I needed to build the building from which I wrote that comment, foundation to studs to Romex to drywall, and also lots of instructions printed on things like bags of concrete, drywall tape, etc., but never for a browser or a mobile phone. I guess you could infer where I think my expertise lies and where it doesn’t. :)

Re: The Opposite of Documentation is Superstition (2020)

#82

Post by KronisLV »

Animats wrote: post #19
fiforpg wrote: post #17

Earlier quoted context omitted.

> 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.

> Cargo cults don't work at all.

The people who take DRY and SOLID as absolute rules might create codebases that will be harder to maintain, but probably won’t go up in flames.

I think cargo cults absolutely do work, same as how people pick Nginx “because it’s fast” while they might need to consider that their Python API probably wouldn’t be bottlenecked even by Apache2 (depending on what you’re doing Nginx might still be the right choice, but for different reasons). Similar to how people might lean towards either Java or .NET for a plethora of shallow reasons - either will work for most problems, so the choice will be good even if the reasoning behind it might be bogus. Same for AMD vs Intel or AMD vs Nvidia etc.

Unless you need to be web scale, then the right answer is clearly MongoDB. /j

Re: The Opposite of Documentation is Superstition (2020)

#84

Post by ChrisMarshallNY »

ChrisMarshallNY wrote: post #30

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 ge…

Just to follow up, I finally got it all working today. No thanks to the "documentation." Lots of trial, and lots of error.

I needed to have charts that you can pinch-to-zoom.

Re: The Opposite of Documentation is Superstition (2020)

#85

Post by rekabis »

> By the end of the experiment, six of the eight pigeons developed nonsensical "superstitions" to get food

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.

Re: The Opposite of Documentation is Superstition (2020)

#86

Post by 392 »

floating-io wrote: post #41
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…

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...

That's a great sign that using it will be more pain than just solving the problem yourself

Re: The Opposite of Documentation is Superstition (2020)

#87

Post by sahmeepee »

IgorPartola wrote: post #80
sahmeepee wrote: post #43

Earlier quoted context omitted.

> 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…

You have read the actual manual for your browser? Multiple browsers? You didn’t google for the answer on how to refresh the pages? Somehow I just don’t feel like this is the literal truth.

If you mean a printed book describing how every feature of (say) Chrome works, then no. They don't produce one. The "manual" for Chrome is Google's support Web pages for the browser, which I have read in conscious preference to the often inaccurate folk knowledge that comes back from a general Google search.
Post reply on HN