SmartmanApps

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.

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 😂

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

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).

I can’t start the tutorial at 1+1=2

But you can put it in the pre-requisites

there’s no need for the apostrophe

Ok, I fixed the typo.

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).

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.

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 read your entire tutorial.

Not very carefully apparently.

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.

It’s hard to write a tutorial.

No it isn't. Assume the reader knows nothing.

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.

a responsibility to somehow make complicated topics easy

That's what tutorials are for! 😂

usually written by Charles Petzold

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.