[Photo: @FelixFoggCircus, by @Karol_Jurga] I’ve been delivering the talk “Let’s stop making each other feel stupid” for a few years now. It’s a popular talk, and a topic that’s close to my heart. H…
The Stupidity Manifesto
LET’S STOP MAKING EACH OTHER FEEL STUPID. Instead, let’s…
ENCOURAGE EVERYONE TO ASK QUESTIONS
Lead by example: Be honest when we’re confused
Value curiosity over knowledge
Prioritise clarity over jargon
Remember we all forget stuff
Get excited about teaching and learning
Acknowledge the broad range of knowledge in our industry, and avoid judging someone if their knowledge doesn’t match ours
I actually was a teacher for a while (Computer Science and Maths), and I still do tutoring. When I started working with Xamarin, with no prior .NET/C#/GUI experience (just shell scripts and programs in DOS and Unix), it became clear as day to me that no-one at Microsoft had the slightest idea how to teach things. That hasn’t changed even now. The documentation is horrendous - they don’t even follow basic grammar rules like spell out an acronym in full the first time, so first time you hit one and you don’t know what it is, now the document is useless (because they haven’t linked to any assumed background knowledge either - have you tried Googling COM to find out what it is?). When I told someone there (who I won’t name) they said “it’s near impossible to cater for all levels”. No it isn’t - you start with the fundamentals (or link to them) and build your way up to the more advanced.
Microsoft documentation…
Here’s my blog on writing a MAUI UI in C# which illustrates how to write a document (though I realised later I missed linking a few things and still need to go back and fix those) - Creating MAUI UI’s in C#
It’s also an issue with their templates - there’s no such thing as a “blank” MAUI app. They stuff a bunch of stuff in there which violates “teach one concept at a time”. I was so relieved when I found out how to make my own templates! (shell be gone! XAML be gone!)
Here are the basic rules of teaching…
I would add to that (for documentation) always spell out your acronyms in full the first time, link to any assumed knowledge, have step-by-step instructions, and make sure you cover different uses from basic to advanced (and don’t damn well use Foo Bar - use a real world example).
You are not logged in. However you can subscribe from another Fediverse account, for example Lemmy or Mastodon. To do this, paste the following into the search field of your instance: !programming@programming.dev
Welcome to the main community in programming.dev! Feel free to post anything relating to programming here!
Cross posting is strongly encouraged in the instance. If you feel your post or another person’s post makes sense in another community cross post into it.
Hope you enjoy the instance!
Rules
Rules
Follow the programming.dev instance rules
Keep content related to programming in some way
If you’re posting long videos try to add in some form of tldr for those who don’t want to watch videos
I actually was a teacher for a while (Computer Science and Maths), and I still do tutoring. When I started working with Xamarin, with no prior .NET/C#/GUI experience (just shell scripts and programs in DOS and Unix), it became clear as day to me that no-one at Microsoft had the slightest idea how to teach things. That hasn’t changed even now. The documentation is horrendous - they don’t even follow basic grammar rules like spell out an acronym in full the first time, so first time you hit one and you don’t know what it is, now the document is useless (because they haven’t linked to any assumed background knowledge either - have you tried Googling COM to find out what it is?). When I told someone there (who I won’t name) they said “it’s near impossible to cater for all levels”. No it isn’t - you start with the fundamentals (or link to them) and build your way up to the more advanced.
Microsoft documentation…
Here’s my blog on writing a MAUI UI in C# which illustrates how to write a document (though I realised later I missed linking a few things and still need to go back and fix those) - Creating MAUI UI’s in C#
It’s also an issue with their templates - there’s no such thing as a “blank” MAUI app. They stuff a bunch of stuff in there which violates “teach one concept at a time”. I was so relieved when I found out how to make my own templates! (shell be gone! XAML be gone!)
Here are the basic rules of teaching…
I would add to that (for documentation) always spell out your acronyms in full the first time, link to any assumed knowledge, have step-by-step instructions, and make sure you cover different uses from basic to advanced (and don’t damn well use Foo Bar - use a real world example).