I think the blogger is more technical than they let on:
- understands how to write footnotes
- structures lists correctly
- runs their own blog with custom domain name.
I’ve known programmers struggle with markdown.
Well that’s because markdown is for documentation, and we all know programmers don’t know how to write documentation.
As a developer, that is also how I read tutorials written by other developers.
People say “RTFM” then you get to the manual and it’s this
Microsoft Manuals…
That is spot on. Usually you would expect the manual to be hit and miss when it comes to troubleshooting but Microsoft is consistently miss, skipping the important parts and details.
Microsofts documentation is also increasingly just outright wrong:
if you spend enough time looking up things about their newer products like M365, defender, or azure, especially when it comes to scripting related to those, there’s a ton of simply outdated info on the official docs that makes it really difficult to figure out why your setup isn’t doing what it’s supposed to.
from changed variable names, to missing functions, to unexplained buttons, etc., etc.
the newer docs are straight up trash!
you’re better off searching around for forum posts or whatever, than using the official docs…
If you are used to documentation like MS’s, then AI responses probably look more reasonable and useful. If AI results look better than your own docs you should feel really bad.
Microsofts documentation is also increasingly just outright _wrong_:
There used to be a spot on joke about Microsoft documentation taking the piss out of the fact that it was always 100% accurate but at the same time pretty useless. That joke hasn’t been relevant for a while.
It’s so frustrating trying to find out how to do something in one of the admin centres for M365 and you find a Microsoft document with exactly what you need in it only to find out that the UI has changed and the steps don’t work now. Did they move it? Did they remove it? Who knows?
our admins are regularly straight up fighting against this bs!
“where the fuck has this fucked off to now?? it was right here last month?!”
so glad I’m not doing MS administration…
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”.
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
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#
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
Good documentation includes both. i.e. step-by-step guide, with explanations. See above.
so either seek recipes with an even lower base level
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:
“Visual Studio (VS) does not (currently) provide a blank .NET Multi-platform Application User Interface (MAUI) template which is in C# only. In this post we shall cover how to modify your new MAUI solution to get rid of the XAML, as well as cover how to do in C# code the things which are currently done in XAML (such as binding). We shall also briefly touch on some of the advantages of doing this.”
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.
it would have to explain to people “how do you use a keyboard”
No it wouldn’t. You just link to resources about pre-requisite knowledge.
and everything from there upwards
Nope. Exact same thing applies to all pre-requisite knowledge.
For 99% of people almost all that is about as understandable as Greek
Now scroll down to the pre-requisite knowledge which has links to things explaining ALL of that.
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)
Exact same number as there is people capable of clicking on the provided links about them in the pre-requisite knowledge section.
which is maybe level 4 and they’ll be totally lost,
…until they read the links in the pre-requisite knowledge, and then they will understand all of it.
I think you’re so way beyond the average person in your expertise in this domain
says person who didn’t even scroll past the introductory paragraph! 😂 You think people try to learn things by reading only the introductory paragraph?? 😂
you don’t even begin to suspect just how little of our domain the average person knows compared to an mere programmer
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
