Earlier quoted context omitted.
> The trouble is that there is a strong correlation between being able to design good interfaces and being able to prepare good documentation. Meaning, where guessing fails, the reference is bound to also fail due to inaccuracies or failing to communicate what you need to know. Which stands to reason as both require concern for how the user perceives the product. I think we're talking about different kinds of guessin…
> Like "I don't know anything, so I'm just going to try "stuff" I find online without really understanding. A reasonable place to start. But fair that you can't stop there if it isn't working. Next step, in my opinion, is to look at the interface more closely to see if it provides any hints. It will most of the time if it is well designed. > But even with the best designed interfaces, not everything is discoverable S…
> A reasonable place to start. But fair that you can't stop there if it isn't working.
It's not a reasonable place to start. You're basically talking about copy-paste coding. Google search, stack overflow, paste in the first answer. Afterwards, ask the dev if they know what they did and why it works, and they won't be able to answer because they don't know.
> Next step, in my opinion, is to look at the interface more closely to see if it provides any hints. It will most of the time if it is well designed.
The people I'm taking about can't and won't do that.
> Sure. That's what the test suite is for, though: To document for users full intent and usage. You're still not going to go to a reference for that. As an added bonus, it is self-validating, so none of the "is it me or is the reference incorrect?" rigamarole.
I'm getting an "I don't need comments because code is self-documenting" vibe here. I disagree with that. Prose is a better way to express many, many things related to code than the code itself or even its test.
Sure, the code is the most authoritative place to find what was implemented, but it's not the best way to find the why or the concepts and thought behind it.