Learning is our bread and butter. Let’s stop making each other feel stupid.
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… Image
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).
bitcrafter@programming.dev 2 months ago
I appreciate this sentiment a great deal in general, but sometimes it is difficult to uphold when I have to regularly deal with “time vampires” who not only require that I explain the same thing to them over and over again beyond reason but who also show no willingness or ability to actually learn the thing that I am explaining to them; at some point I just run out of patience and start ignoring them to the extent that I am able.
emptyother@programming.dev 2 months ago
The way I see it, explaining others also helps me understand it better. If its so basic (or too advanced) that I get nothing out of explaining, then I leave it to better suited people to help them instead. Being on these kindsa forums, its supposed to be enjoyable for both the teacher and the student. I don’t see any shame in dropping it as soon as it turns frustrating.
SmartmanApps@programming.dev 2 months ago
There’s a saying - if you want to learn something then teach it (even to a rubber duck ;-) ).
jadero@programming.dev 2 months ago
This may not apply to your situation, but I found that most of my problems like this were related to “general vs specific”.
Many people have difficulty generalizing from specific instructions so they need help every time something looks different to them. In an extreme case, found a person unable to choose a font in the header of a word processing document because the only thing they’d ever been shown was how to choose a font in the body of the document. It’s not even that they were particularly dense, it’s that they’d seen so much unexpected and unexplained variation in other areas that they started assuming that everything is an isolated task with a potentially distinct set of procedures. Now that I’ve switched from Windows to Linux, I’m getting a better understanding of how that happens, with many applications using different hotkeys, not implementing what I think are sensible “tab ordering”, etc.
Many people have difficulty going from the general to the specific without also seeing several specific examples in a variety of scenarios. That kind of thing normally requires more formalized training. If their only exposure to your knowledge is through ad-hoc help desk kinds of interactions, there will be no opportunity to put everything together.