They have even forgotten one of the most basic grammar rules - always fully spell out an acronym the first time you use it. Looking at you MicroSoft (MS). No, I don't know what TLA* is, and now this document is completely useless to anyone who doesn't know what TLA is, especially since you've also not linked to any resources about TLA
Sounds like typical Microsoft documentation to me. Explains in great detail what .NET is, where you can download it from, then jumps straight to the advanced topic they're covering without any of the intermediate knowledge covered or even linked to (but perhaps referred to only vaguely in passing as an acronym, again with no link, this time no link to what "TLA" is actually short for, so you're searching for it is fruitless as well).
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.
They seem to exist solely as a reminder to those who already know
Perfect description of the entire Microsoft .NET documentation, signed, .NET beginner who not only didn't have a .NET background, but not even a Microsoft programming background (which is also heavily assumed throughout - way to make newbies feel completely unwelcome in your ecosystem!).
I’ve seen cases where the documentation of the rather critical parameter “flags” was just the word “flags”.
In Microsoft documentation it would just say "FLGs", with no explanation of what FLG is, nor any links to resources about FLGs. you either already know what it is or you now can't continue any further with the documentation (because a search for FLG also fails to find what it is). Throughout their documentation it is heavily assumed you are a long-time Microsoft programmer and already know all of this. i.e. it is completely unwelcoming to Microsoft beginners (and even some who aren't beginners)
I think TLA means “Three Letter Acronym” in some circles
Yes, that was why I used it. Microsoft doco is full of unexplained TLA's - you have to already know what it means and how to use the thing. You knew what TLA meant. Now read the Miscrosoft doco where you don't know what any of the MS TLA's mean, and they don't tell you.
Imagine a chemistry lab tutorial aimed at 9th grade students getting “as a non-chemist, this reads as gibberish” comments from first graders. Nobody would blame the tutorial authors
I tutor Maths. I have a Year 12 student who has forgotten things they were taught in Year 8, and the teacher has done no revision of it in class. Now guess why this student needs a tutor 😂
People need to start putting in the effort.
The people writing the documentation, yes. They need to say what the prerequisite knowledge is, and include links to it for those who don't know it (or remember it). Only takes a few minutes to do that. See Creating MAUI UI's in C#
A lot of experienced people say that, and it isn't to a beginner. The infamous example in Maths circles is "the proof is left as an exercise for the reader". In other words, "I couldn't be bothered writing this because I'm assuming you already know how to do it".
It’s a curse of knowledge
Yep, the people who write the Microsoft documentation assume that the readers know everything they already know.
If it’s all gobbledygook to you, then you weren’t the target audience.
Beginners are the target audience for tutorials. Many tutorials are written in gobbledygook. See Microsoft documentation, which would've instead said GDG, and assumed you knew what GDG was.
Most developers are writing for developers who have approximately the same skill level and knowledge
If they had the same skill level and knowledge then they wouldn't need a tutorial to begin with.
The vast majority of tutorials out there are definitely not aimed at beginners
And that's precisely the problem with the vast majority of tutorials.
Now, if it were 95% easy to follow, and then there was one step that was only a few words long and made no sense at all, that would be the typical badly written tutorial
Microsoft: Now all you have to do is add in a GDG
I must have skimmed through 30 tutorials aimed at people roughly my skill level before I finally found one that explained the missing bit
Now imagine reading Mircosoft documentation and not being able to find anything which explains what GDG is. Classic "rest of Owl".
they’re actually really hard to write
No they're not. You include what the pre-requisite knowlege is, along with links to resources about the pre-requisite knowledge. See Creating MAUI UI's in C#
“just add this to the config folder” - which folder? Where?
This is one of the biggest problems with Microsoft documentation (and maybe other ecosystems too). Doesn't include any "using" statements in the snippet, leading to copying the code not working, because you don't know what DLL this is using. They talk about 2 lines, and show you 2 lines, but the 2 lines don't work without 1 or 2 other lines which they have left out. Happens every single time
not correctly steering the user towards the relevant documentation about configuration values
Microsoft documentation never links to anything else at all. If you don't know how to do this thing they're talking about, well now you have to go find a Youtube by some Indian programmer about it
there’s a bit of a disconnect because a lot of tutorials exist that base level of knowledge that a complete beginner doesn’t have
Yep. The man pages are so not user-friendly. I have always said that Unix is very powerful, but not the least bit user-friendly. Welcome to low adoption.
Is “prerequisite knowledge” a foreign concept to people these days?
Apparently so.
RTFM means that you should use the available resources to learn
Except the manuals are written like this, and don't cover pre-requisite knowledge at all - don't even link to it!
There’s a whole internet full of them
Microsoft doco "now add TLA to it", don't say what TLA is, don't link to what TLA is, searching for TLA doesn't tell you what it is. There most certainly is a whole internet full of blogs about "TLA", but I don't even have any keywords, and can't find any of the "TLA" that Microsoft is talking about. The documentation is literally useless to anyone who doesn't already know what "TLA" is.
There are no shortcuts to understanding
There are no shortcuts to writing good documentation
you can’t expect every task-oriented guide to explain how to write a main().
But you can certainly expect them to link to resources about pre-requisite knowledge, like I did in Creating MAUI UI's in C#.
“first, install npm and npx and npy and npppp2 and then run ‘npz create-huge-boilerplate-folder’. Now go edit arbitrarily_named_file.yaml to add requirements a, b, and banana. Now you can edit path/to/hidden/entrypoint.jsx to return ‘Hello, World!’ and then run ‘npz bloated-dev-http-server’ and navigate to http://127.0.0.1:9001/index to view it! Simple!”
I was forced to try and use it as a brand new to Microsoft (not just .NET, all of Microsoft) programmer (my experience was in other ecosystems). Not recommended.
you’re better off searching around for forum posts or whatever, than using the official docs
Yep, that's why I started the Lemmy .NET MAUI Community - try and reassemble the collective experts who got scattered when Microsoft shutdown the old Xamarin forum - they had been invaluable when I was trying to learn Xamarin from the Microsoft resources.
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 😂
I’m sorry to tell you, friend, that your article does this too
Nope.
You don’t explain what XAML is, for instance
You know the article is about how to write a page and NOT use XAML, right?? 😂 If you don't know what it is then you don't need to (hence why I point out that it isn't pre-requisite knowledge). If you do know what it is then that's probably what brought you to my page to begin with - stop using it! 😂
Certain sentences almost read like the satire you posted:
Now read the links provided in the pre-requisite knowledge. You're the second person who thinks people learn things by reading the first paragraph only.
You also tell the reader to “edit the relevant line” which doesn’t help a total beginner
Now read the links in the pre-requisite knowledge, clone the repo, follow the instructions up to that point in the article, and guess which line you're on! 😂
I’m sure you’ll get there eventually
It's there already, if you had just bothered reading it all and following the instructions, instead of just criticising without even trying it
Just keep in mind that most people do not want to be technical writers
Probably because of people like you who criticise them without even trying to follow the directions to begin with. I'm guessing you also submit issues which say "It doesn't work. Please fix"
Classic example of someone who wrote tutorials like the type being satirised.
If it’s worthwhile doing it’s hard
Writing good tutorials isn't hard. You just have to not assume background knowledge of anything you're writing about. If you write it for beginners, then literally anyone can follow it.
Cool but nobody’s about to link to prerequisite information like typing on a keyboard.
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?
Same for math, a book focusing on integration isn’t going to say “read this book for the basics of addition btw”
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...".
And why should one even cater to that?
Because it's useless to a large chunk of your audience if you don't.
If a person is interested enough they can just… look up the things they don’t understand,
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"
that’s not exactly hard
It's very hard when you have no search keywords at all to work with.
I’m sorry dude, but the other person is completely correct
No they're not.
You don’t explain a lot of things
You mean all the things that have links to resources about them in the pre-requisite knowledge section? 😂
For example Git and GitHub are both prerequisites that you don’t mention
Now go read through the links in the pre-requisite section. Also, they're not pre-requisites - it isn't necessary to know how to use them, given cloning the repo is optional - hence not listed as pre-requisites. See how that works?
Knowledge of layout is also a prereq
No it isn't. I specifically cover exactly that. I see you didn't read it.
You don’t explain what binding is.
Yes I do! 😂 As do the links in the pre-requisite knowledge. Again showing you didn't read it
There’s a ton of typos.
says person not identifying any
You missed putting certain things in code blocks
You ever tried doing that on dev.to? Guess what? There's no tutorials for it! 😂 (the thing they said to do doesn't work)
You should every once in a while show the full class or file so the reader knows what they missed
It's done at the beginning. Also there's the repo. Again showing you didn't read it.
There’s a lot that could be improved here.
says person with made-up criticisms from not having actually read through it.
I don’t want to make this a “gotcha”, but you say no xaml knowledge needed but then talk about it and have the reader touch them (mostly delete).
I only have them delete the XAML files. You don't need to know anything about what's inside a file to delete it 😂 Also, I only talk about the benefits of getting rid of them, which also doesn't require any knowledge of XAML.
You say you usually delete this xaml file but I don’t need to do that. Why?
No I don't! I say disabling implicit usings is optional, and do explain why I do it, then delete the XAML files. You seem to have conflated 2 successive paragraphs.
I thought I didn’t need to know xaml?
You don't. They're never used anywhere in the whole thing. We only delete the XAML files, then replace them with C#.
I think your tutorial depends too much on your editor UI
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.
It reminds me of those tutorials (often written by Microsoft) where the IDE has changed enough to break the tutorial.
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.
There’s a difference between “a beginner” and “someone who is very experienced but hasn’t done X”.
If they haven't done X then they are a beginner at doing X - no difference - this is in fact the target audience for many tutorials. The other things which aren't covered in the tutorial you put in the pre-requisites.
not a “developer who understands and uses 90% of the same tech stack, but is looking to do something new related to it”
and yet, a lot of tutorials written for developers who have used 90% of it are written just as badly, hence the huge upvotes.
If it were aimed at true beginners it would be written completely differently
That's the point! Many tutorials need to be written completely differently! 😂 For starters all of the ones at Microsoft.
A university teacher preparing a lecture about shakespeare doesn’t write the same lecture if their audience is a bunch of 5 year olds
That's because the course has pre-requisites that you must have passed before you can enrol in that course - if you don't, then you have to go study those things before you'll be allowed to enrol - and they are explicitly spelt out in the guide to enrolling, hence the professor can write the lecture safe in the knowledge that all students in his class have completed all of the necessary pre-requisites.
You know that’s not true, right?
I know it's absolutely true. Even my threads on Maths are written with the assumption that the reader doesn't know all of the background knowledge (in fact are written quite intentionally for those who are being bullied by gaslighters, and they lack the proof to debunk them).
So maybe the tutorial the satirist was satirising just wasn’t quite aimed at the satirist
I think many people here have seen exactly such tutorials - indeed aimed at them - hence the huge upvotes. See Microsoft tutorials that never link to any pre-requisites at all (leaving you looking for a Youtube by an Indian programmer).
Of course. But that wasn’t the complaint/satire of the satirist whose article we’re discussing
I think you'll find that's a huge part of the complaint - unexplained terminology. See Microsoft tutorials that never tell you what any of their TLA's are, nor link to any explanations of them, exactly as is satirised
Others are debating the point about the doc itself
Most of those others have shown they only read the first paragraph (which is literally the introduction, not the start of the tutorial itself).
just because you enjoyed doing it, doesn’t mean others do, or have the time
I never implied otherwise. I simply used it to show it only takes a few minutes to include pre-requisites for the thing you are writing, compete with links to relevant resources. Microsoft documentation never does either of those things, and those people are paid to write it. Then they ignore your issues that you raise. I forget his name now, but I remember one guy there who did this all the time - would just close your issue and not update the document. I remember one time James Montemagno fixed up an issue I raised, but this other guy, never. I just gave up on raising issues. I'm surprised his name isn't burnt into my memory with PTSD 😂
It’s like the difference between going to a mechanic that has you sit by the coffee machine in the office ...
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.
if I’m unable to get that version of your IDE, the tutorial becomes useless.
No it doesn't. Clicking on the link gives you the latest version, which obviously is above the minimum version.
without unnecessary concealment of basic information dependent on an IDE
Haven't concealed anything - it's there in the pre-requisites
“I did this in my IDE: here’s what it did”
I have many screenshots showing exactly that.
The reader could in principle use any text editor
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 an IDE tutorial
It's not meant to be. It covers what you need to know to do what I have done in the blog.
And you made another Microsoft-grade tutorial
Nope! They don't include pre-requisites at all, never mind links to them, never mind step-by-step processes with screenshots, etc.
Yes I literally do. "gives us a consistent look throughout the app, and in fact a consistent look across all our platforms (because we are now replacing the default colours with our own colours)", etc.
The first link is a download link.
It's a download page. Scroll down past the download link.
Do you really need me to go paste all of the text from those pages here into a comment so you can see for yourself?
I just pasted screenshots showing where you can go deeper as needed on the actual pre-requisites.
this either needs to be combined with the first sentence or needs to be capitalized
It's a reserved keyword, always in lower-case.
you also switch between colour and color numerous times
color is a reserved keyword, colour is correct English (since I'm not American).
there’s more
And several that you've referred to already are in fact not typo's.
Just stop arguing about having a perfect tutorial
I never said that Mr. Strawman. I gave it as an example of how to cater to all levels of reader. i.e. pre-requisite links, etc.
Claiming that you have is honestly ridiculous
And you claiming that I did is ridiculous.
I also would never choose to do a tutorial on dev.to.
It's there because that's where some of the MAUI team post blogs themselves - all in one place. - but good on you for criticising me without even asking why it's there.
You never once show the full file in the article
Again, yes I do, at the beginning
so stating that you need to leave your article to see the full code is the exact opposite of what your tutorial has stated
No it isn't. I stated that was optional at the beginning.
your tutorial is severely lacking
says person picking on typo's (some of which aren't) and didn't explore any of the pages linked to in the pre-requisites. I guess you expect me to re-invent the wheel in the latter case...
continue writing tutorials like this one
that have links to pre-requisites, which is the whole point to begin with, but sure, pick on some typo's (some of which aren't) because you can't refute the actual point... 🙄
Not sure how many times I need to tell that that it isn't a pre-requisite.
… I did.
No you didn't. I just added screenshots in my other reply pointing out all the links that you didn't click on.
you mention commits.
for those who are taking the option of following the repo.
Knowing wtf you are talking about is a prerequisite to literally understanding the words you are typing
You think people would be following along in the repo if they didn't know what a repo was?? 😂
To anyone that knows nothing about programming your words are completely nonsense here
Why would "anyone that knows nothing about programming" be reading a blog about how to write a MAUI page in C# instead of XAML? 😂 And, again, this is covered by the links in the pre-requisites, the whole point to begin with.
they will think “then why did this author mention it?”
Because it's optional
The first mention of layouts is when you
...go read the information at the pre-requisite links.
which is nonsense to someone that doesn’t know anything about layouts
And why would "someone that doesn’t know anything about layouts" be reading a blog about layouts in MAUI? 😂
you literally just had us delete it!
I also covered the process for (re)creating the whole project at the beginning, for those who didn't have the common sense to read through what what was going to happen after we delete it, or they can click on the first version in the repo, and these are Windows developers, so it's probably still in the recycle bin, so yes, they most definitely can.
you said we don’t need to click on the link to the code
That's right.
you said everything would be provided in the article!
Yep, including links to pre-requisites.
All of which are false at this point
Nope, none of which are false.
WTF are ScrollView and VerticalStackLayout
Covered by links in the pre-requisitesand subsequent directions on what to do.
This requires prerequisite knowledge of how layouts work.
Covered at the pre-requisite links.
This is not in any of the prerequisite links
I already proved you didn't look at any of the links there, like...
Instead of writing that snarky comment you could’ve instead used the web for its original purpose and conduct your own research and not bug strangers on the internet to do your bidding
You're not the only one they're doing it to (I went to their profile to see if this is a pattern, and it sure is).
so why even bother with memorizing if I can calculate it fast enough
The standard is to be able to answer a times table question in 2 seconds, so if it's taking longer than 2 seconds to calculate it then it's not fast enough.
As a teacher, no, memorization is an important step before understanding
Yep, same. Without fail the kids I run into who are bad at Maths and "hate Maths" have been poor at mental arithmetic. i.e. not keeping up with what is being taught because they're still struggling with the number-crunching. Once they get up to speed with mental arithmetic their marks improve and they don't hate Maths anymore.
Computer Science Courses that Don't Exist, But Should ( prog21.dadgum.com )
How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner - annie's blog ( anniemueller.com )
Google just broke *all* third-party YT clients, including yt-dlp; a full JS implementation is now required. ( github.com )
cross-posted from:...
[Thread, post or comment was deleted by the author]