Skip Navigation

💡𝚂𝗆𝖺𝗋𝗍𝗆𝖺𝗇 𝙰𝗉𝗉𝗌📱

@ SmartmanApps @programming.dev

Posts

1220
Comments

1145
Joined

2 yr. ago

Moderating

.NET MAUI programming.dev

Windows Development programming.dev

7mo ago

How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner - annie's blog
Jump
💡𝚂𝗆𝖺𝗋𝗍𝗆𝖺𝗇 𝙰𝗉𝗉𝗌📱 @programming.dev 7mo ago

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.

7mo ago

How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner - annie's blog

Jump

💡𝚂𝗆𝖺𝗋𝗍𝗆𝖺𝗇 𝙰𝗉𝗉𝗌📱 @programming.dev 7mo ago

a responsibility to somehow make complicated topics easy

That's what tutorials are for! 😂

7mo ago

How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner - annie's blog

Jump

💡𝚂𝗆𝖺𝗋𝗍𝗆𝖺𝗇 𝙰𝗉𝗉𝗌📱 @programming.dev 7mo ago

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.

7mo ago

How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner - annie's blog

Jump

💡𝚂𝗆𝖺𝗋𝗍𝗆𝖺𝗇 𝙰𝗉𝗉𝗌📱 @programming.dev 7mo ago

And you don’t need to warn me that an “s” is coming.

No idea what you're talking about.

you have no experience with that particular thing

In other words, you are a beginner with that particular thing.

It’s not for someone who has never used any of those technologies

It might be if that is what they are needing to learn. Reading tutorials is usually needs-driven. Think inheriting legacy code

doesn’t understand anything about them

You know that's what tutorials are for in the first place, right?

Ah, I can see you never write tutorials,

Ah, I can see you've never written any good tutorials

You have no idea what you’re talking about

Says someone who just said someone with no experience at something is somehow not a beginner with it 😂

7mo ago

How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner - annie's blog

Jump

💡𝚂𝗆𝖺𝗋𝗍𝗆𝖺𝗇 𝙰𝗉𝗉𝗌📱 @programming.dev 7mo ago

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"

7mo ago

How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner - annie's blog

Jump

💡𝚂𝗆𝖺𝗋𝗍𝗆𝖺𝗇 𝙰𝗉𝗉𝗌📱 @programming.dev 7mo ago

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 😂

7mo ago

How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner - annie's blog

Jump

💡𝚂𝗆𝖺𝗋𝗍𝗆𝖺𝗇 𝙰𝗉𝗉𝗌📱 @programming.dev 7mo ago

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.

7mo ago

How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner - annie's blog

Jump

💡𝚂𝗆𝖺𝗋𝗍𝗆𝖺𝗇 𝙰𝗉𝗉𝗌📱 @programming.dev 7mo ago

As a software developer with 10+ years in .Net.

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.

7mo ago

How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner - annie's blog

Jump

💡𝚂𝗆𝖺𝗋𝗍𝗆𝖺𝗇 𝙰𝗉𝗉𝗌📱 @programming.dev 7mo ago

“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!”

Yep, Microsoft doco is like that too

7mo ago

How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner - annie's blog

Jump

💡𝚂𝗆𝖺𝗋𝗍𝗆𝖺𝗇 𝙰𝗉𝗉𝗌📱 @programming.dev 7mo ago

There’s amazing

IBM

and terrible manuals everywhere.

Microsoft

7mo ago

How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner - annie's blog

Jump

💡𝚂𝗆𝖺𝗋𝗍𝗆𝖺𝗇 𝙰𝗉𝗉𝗌📱 @programming.dev 7mo ago

that you already put in more effort than one can expect by writing a tutorial to begin with

Nope. If a job is worth doing, it's worth doing well.

7mo ago

How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner - annie's blog

Jump

💡𝚂𝗆𝖺𝗋𝗍𝗆𝖺𝗇 𝙰𝗉𝗉𝗌📱 @programming.dev 7mo ago

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

7mo ago

How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner - annie's blog

Jump

💡𝚂𝗆𝖺𝗋𝗍𝗆𝖺𝗇 𝙰𝗉𝗉𝗌📱 @programming.dev 7mo ago

Not to mention this is mostly in unpaid FOSS

Paid documentation writers at Microsoft are absolutely horrible at it too. That's why I can relate to the post so much

7mo ago

How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner - annie's blog

Jump

💡𝚂𝗆𝖺𝗋𝗍𝗆𝖺𝗇 𝙰𝗉𝗉𝗌📱 @programming.dev 7mo ago

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

7mo ago

How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner - annie's blog

Jump

💡𝚂𝗆𝖺𝗋𝗍𝗆𝖺𝗇 𝙰𝗉𝗉𝗌📱 @programming.dev 7mo ago

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#

7mo ago

How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner - annie's blog

Jump

💡𝚂𝗆𝖺𝗋𝗍𝗆𝖺𝗇 𝙰𝗉𝗉𝗌📱 @programming.dev 7mo ago

RTFM

The problem is the manuals which are written exactly as described in the post

7mo ago

How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner - annie's blog

Jump

💡𝚂𝗆𝖺𝗋𝗍𝗆𝖺𝗇 𝙰𝗉𝗉𝗌📱 @programming.dev 7mo ago

“it’s very easy!”

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.

7mo ago

How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner - annie's blog

Jump

💡𝚂𝗆𝖺𝗋𝗍𝗆𝖺𝗇 𝙰𝗉𝗉𝗌📱 @programming.dev 7mo ago

use developer language

Microsoft uses Microsoft language, and the only people who understand it are people who have been Microsoft programmers for a long time.

sitting in the bubble of experts

Yep, the Microsoft ecosystem is completely unwelcome to newbies. It's by experts for experts, and everyone else can go to hell

7mo ago

How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner - annie's blog

Jump

💡𝚂𝗆𝖺𝗋𝗍𝗆𝖺𝗇 𝙰𝗉𝗉𝗌📱 @programming.dev 7mo ago

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#

7mo ago

How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner - annie's blog

Jump

💡𝚂𝗆𝖺𝗋𝗍𝗆𝖺𝗇 𝙰𝗉𝗉𝗌📱 @programming.dev 7mo ago

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.