“Hello! I am a developer. Here is my relevant experience: I code in Hoobijag and sometimes jabbernocks and of course ABCDE++++ (but never ABCDE+/^+ are you kidding? ha!) and I like working with Shoobababoo and occasionally kleptomitrons. I’ve gotten to work for Company1 doing Shoobaboo-ing code things and that’s what led me to the Snarfus. So, let’s dive in!
For “all documentation” to “cater to all levels” it would have to explain to people “how do you use a keyboard” and everything from there upwards, because there are people at that level hence it’s part of “all levels”.
I mean the your own example of good documentation starts with an intro of “goals” saying:
For 99% of people almost all that is about as understandable as Greek (expect for Greek people, for whom it’s about as understandable as Chinese).
I mean, how many people out there in the whole World (non-IT people as illustrated in the actual article linked by the OP) do you think know what the hell is “Visual Studio”, “.Net”, “Multi-platform Application User Interface”, “template”, “C#”, “XAML”, “binding” (in this context).
I mean, if IT knowledge was a scale of 1 to 10 with 10 the greatest, you’re basically thinking it’s “catering to all levels” when an explanation for something that is level 8 knowledge (advanced programming) has a baseline required level of 7 (programming). I mean, throw this at somebody that “knows how to use Excel” which is maybe level 4 and they’ll be totally lost, much less somebody who only knows how to check their e-mail using a browser without even properly understanding the concept of "browser (like my father) which is maybe level 2 (he can actually use a mouse and keyboard, otherwise I would’ve said level 1).
I think you’re so way beyond the average person in your expertise in this domain that you don’t even begin to suspect just how little of our domain the average person knows compared to an mere programmer.
No it wouldn’t. You just link to resources about pre-requisite knowledge.
Nope. Exact same thing applies to all pre-requisite knowledge.
Now scroll down to the pre-requisite knowledge which has links to things explaining ALL of that.
Exact same number as there is people capable of clicking on the provided links about them in the pre-requisite knowledge section.
…until they read the links in the pre-requisite knowledge, and then they will understand all of it.
says person who didn’t even scroll past the introductory paragraph! 😂 You think people try to learn things by reading only the introductory paragraph?? 😂
And yet, weirdly, if you keep reading you’ll find it caters to people who know nothing about it 😂
Cool but nobody’s about to link to prerequisite information like typing on a keyboard. Same for math, a book focusing on integration isn’t going to say “read this book for the basics of addition btw”.
And why should one even cater to that? If a person is interested enough they can just… look up the things they don’t understand, that’s not exactly hard
they say to someone who does indeed link to all pre-requisite knowledge. 😂 You know some Tech people do indeed recommend doing a touch-typing course, right?
I’m a Maths teacher. You’ll find that Maths textbooks do indeed run through any pre-requisites for the topic. e.g. “We discussed back in Chapter 2…”.
Because it’s useless to a large chunk of your audience if you don’t.
No they just can’t, not when no information at all has been given on what this is so that you have something to search for. See Microsoft doco where they use TLA’s, don’t tell you what the TLA is short for, don’t link to any information about the TLA, and searching for “TLA” (since they’ve not told you what TLA is short for) fails to bring up any information about this thing they are talking about. Now the tutorial is completely useless to you because you have no idea what they’re talking about and can’t find anything about what they’re talking about. “Draw the rest of the owl”
It’s very hard when you have no search keywords at all to work with.
No, you’re not supposed to follow years of computer science courses in a university. A good tutotial will provide all prerequisite knowledge for you. Including high school.