“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!
The more advanced the level of knowledge on something the more foundation knowledge somebody has to have to even begin to understand things at that level.
It would be pretty insane to in a tutorial for something at a higher level of expertise, include all the foundational knowledge to get to that level of expertise so that an absolute beginner can understand what’s going on.
Imagine if you were trying to explain something Mathematical that required using Integrals and you started by “There this symbol, ‘1’ which represents a single item, and if you bring another single item, this is calling addition - for which we use the symbol ‘+’ and the count of entities when you have one single entity and ‘added’ another single entity is represented by the symbol ‘2’. There is also the concept of equality, which means two matematical things represent the same and for which the symbol we use is ‘=’ - writting this with Mathematical symbols, ‘1 + 1 = 2’” and built the explanation up from there all the way to Integrals before you could even start to explain what you wanted to explain in the first place.
That said, people can put it in “recipe” format - a set of steps to be blindly followed without understanding - but even there you have some minimal foundational knowlegde required - consider a cooking recipe: have you ever seen any that explains how does one weight ingredients or what is “boiling” or “baking”?
So even IT “recipes” especially designed so that those with a much lower level of expertise than the one required to actually understand what’s going on have some foundational knowledge required to actually execute the steps of the recipe.
Last but not least I get the impression that most people who go to the trouble of writting about how to do something prefere to do explanations rather than recipes, because there’s some enjoyment in teaching about something to others, which you get when you explain it but seldom from merely providing a list of steps for others to blindly follow without understanding.
So, if one wants to do something way above the level of expertise one has, look for “recipe” style things rather than explanations - the foundational expertise required to execute recipes is way lower than the one required to undertand explanations - and expect that there are fewer recipes out there than explanations. Further, if you don’t understand what’s in a recipe then your expertise is below even the base level of that recipe (for example, if somebody writes “enter so and so in the command prompt” and you have no fucking clue what a “command prompt” is, you don’t meet the base requirements to even blindly follow the recipe), so either seek recipes with an even lower base level or try and learn those base elements.
Further, don’t even try and understand the recipe if your expertise level is well below what you’re trying to achieve: sorry but you’re not going to get IT’s “Integrals” stuff if your expertise is at the level of understanding “multiplication”.
Something that’s quite interesting is that apparently one of the core components of how Latin and Greek used to be taught in fancy public schools (especially in like, Isaac Newton’s era) was that students would be made to copy out sections from classical literature (such as the Odyssey). Obviously this would be happening alongside lessons involving basic grammar, but I’ve seen some scholars suggest that this kind of blind repetition was a key component to the language learning, and that it may even be useful for learning languages in a modern context.
I Prefer a playbook to a recipe card. The playbook should spell out the goal and the 'why’s of the steps. Because if the process throws an error due to upgraded code etc, then you can be stuck at step one with no path forward. With some playbook annotation you at least know expected out come and why you are running a command etc.
When I have gone to docker hub I always view multiple images and see what their writeup is like. Some just assume you 100% know all dockers subtleties, some have a one liner, but there will be a helpfull soul who spells out what steps to do, and what the best options to set etc. Like a mini tutorial.
I find the mini tutorial to be widely beneficial, because it removes the blackbox nature, and gives new onboarding users a chance to grasp the concepts docker works with.
It’s like the difference between going to a mechanic that has you sit by the coffee machine in the office while they change your brakes and they come back and say “I swapped the new pads in”, vs them pulling up a chair in the shop and explaining the process “here I’m wirebrushing the back of the wheel and the hub, to make sure when it goes back on there is no corrosion debris stopping a parallel fit…now I’m applying high temp grease so that the hub and wheel don’t sieze together from corrosion and make next removal easy”
The info is probably useless to a seasoned mechanic that had a broken hand so had somebody else do their brake work, but highly useful to the next gen of person that can absorb it and know whats and whys.
Good example. I just wanted to add that the place I go to for tyres, if there’s some kind of issue (like with balance or alignment), sometimes they even take me into the workshop (where customers are usually not allowed) to show me what the issue is.
Yeah, that’s much better.
Personally I detest not understanding what’s going on when following a guide to do something, so I really dislike recipe style.
That said, I mentioned recipes because recipes meant to be blindly followed are the style of guide which has the lowest possible “required expertise level” of all.
I supposed a playbook properly done (i.e. a dumbed down set by step “do this” guide but with side annotations which are clearly optional reading, explaining what’s going on for those who have the higher expertise levels needed to understand them) can have as low a “required expertise level” as just a plain recipe whilst being a much nicer option because people who know a bit more can get more from it that they could from just a dumbed down recipe.
That said, it has to be structured so that it’s really clear that those “explanation bits” are optional reading for the curious which have the knowhow to understand them, otherwise it risks scaring less skilled people who would actually be able to successfully do the taks by blindly following the step-by-step recipe part of it.
Yep, totally. This past year I spent a lot of time setting up an LMS with content.
I included sections that were tips, good to know, for awareness, etc.
Maybe only 1 out of every 20 users might expand the section, but if they do then there is a clear explanation of why this particular thing functions this way and how to make it work in alternate usecases. Images and explanation, before and after, etc.
You don’t need to include it all. You just need to mention it as pre-requisite knowledge, and link to resources about it for those who don’t have that knowledge. See Creating MAUI UI’s in C#
Good documentation includes both. i.e. step-by-step guide, with explanations. See above.
All documentation should cater to all levels. See above.
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.
I think your tutorial depends too much on your editor UI. It reminds me of those tutorials (often written by Microsoft) where the IDE has changed enough to break the tutorial. This made the tutorial completely useless, because none of them would explain what I actually needed: the magic thing their IDE did in terms of essentials (text files, basic commands), so I could reproduce the effect.
This is different in the unix world, which favors tool-agnostic approaches in terms of text files & basic commands. Even as tooling & technology changes, I can usually look up the meaning of the text & those commands to update them.
That’s the most important I think: not the answer itself, but where the answer comes from, so I can go back there when I need to.
You mean the UI which is specified in the pre-requisites, that UI? 😂 It’s not a bug, it’s a feature - no bloat from going through everything twice (once for VS, once for VS Code). That’s why it’s in the pre-requisites.
You know I needed to write this because Microsoft hasn’t written a tutorial for this topic, at all, right? That does remind me though, MAUI have changed the parameters for Grids - I better check that part of my tutorial is still valid.
It’s a bad one: if I’m unable to get that version of your IDE, the tutorial becomes useless. If it had stuck to programming essentials like the source code & configuration files, then it’d have enduring value as the reader could understand without unnecessary concealment of basic information dependent on an IDE.
Not implied: the tutorial would properly focus on the programming without IDE complications as it shows the files generated & dependencies linked. (eg, “I did this in my IDE: here’s what it did”.) The reader could in principle use any text editor. It’s not an IDE tutorial.
And you made another Microsoft-grade tutorial: that’s not a compliment.
No it doesn’t. Clicking on the link gives you the latest version, which obviously is above the minimum version.
Haven’t concealed anything - it’s there in the pre-requisites
I have many screenshots showing exactly that.
No they can’t. Several times I cover the Intellisense options which make it easy. This isn’t available in a text editor, hence the pre-requisite of using Visual Studio if you want to follow this blog.
It’s not meant to be. It covers what you need to know to do what I have done in the blog.
Nope! They don’t include pre-requisites at all, never mind links to them, never mind step-by-step processes with screenshots, etc.