How about that worst of both worlds, the tutorial where the author starts out writing as if their audience only barely knows what a computer is, gets fed up partway through, and vomits out the rest in a more obtuse and less complete form than they would’ve otherwise?
-
Turn on your computer. Make sure you turn on the “PC” (the big box part) as well as the “monitor” (TV-like part).
-
Once your computer is ready and you can see the desktop, open your web browser. This might be called “Chrome”, “Safari”, “Edge”, or something else. It’s the same program you open to use “the Google”.
-
In the little bar near the top of the window where you can write things, type “https://www.someboguswebsite.corn/download/getbogus.html” and press the Enter key.
-
Download the software and unarchive it to a new directory in your borklaving software with the appropriate naming convention.
-
Edit the init file to match your frooping setup.
-
If you’re using Fnerp then you might need to switch off autoglomping. Other suites need other settings.
-
Use the thing. You know, the thing that makes the stuff work right. Whatever.
Congratulations! You’re ready to go!
Too real.
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).
I think TLA means “Three Letter Acronym” in some circles. So like, DBA would be a TLA meaning “database administrator” for example. Didn’t read the article to get the context though, so not sure if it fits
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.
Yes, TLA is a three letter acronym. A four letter acronym, on the other hand, is an ETLA, or “Enhanced Three Letter Acronym”. For advanced cases, you can get an EETLA (or XETLA) for Expanded/Extended Enhanced Three Letter Acronym.
Just so you know.
-
Controversial, but: Skill issue.
I do a lot of FOSS work. I dont write docs for everyone most of the timr. I write docs for those already educated on most of the items. This still applies, and is accessible to anyone:
If you don’t know the word, look it up in the dictionary.
I don’t want to downplay frustrations, I know those are real, but most people writing these things aren’t paid.
Note: If a Dev complains their idea isn’t adopted and the docs suck, that’s another story.
Edit: And the article seems to be by a career writer, so it makes sense from their perspective, but some more expansive thinking on their part about how a developer isn’t staffed to do their job, too, would be helpful.
On the flipside I’ve encountered docs that expect the reader to already understand the functionality in order to be able to use the docs. They seem to exist solely as a reminder to those who already know.
There’s a reason I don’t bother running my own mailservers anymore!
Oh man, this I do hate. If you have terminology in your app, that is not a standard, please, please define it.
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!).
deleted by creator
I found this website/article by accident on neocities, it’s about a tutorial Git. Though it’s a bit bare-bones I respect the effort.
Would be nice to see what all of you think. Considering this is a thread on tutorials. I hope this kid succeeds in life.
Yeah, I use a software that had amazing documentation when they had a publishing company division. When the publisher was gone the documentation is at most a glorified of glossary.
Help on Feature XYZ: Feature XYZ allows you to use FeatureXYZ
most people writing these things aren’t paid.
I wasn’t paid to write Creating MAUI UI’s in C#. Didn’t stop me from doing a proper job of it.
Others are debating the point about the doc itself, so I won’t go there, but just because you enjoyed doing it, doesn’t mean others do, or have the time.
I happen to write really detailed documentation, because I like to, I like the formality of it. However, as I stated in my other comment my complaint is about the assumptions made in the blog post. Specifically:
I just felt like if we rewrote the blog post as a “What a writer who’s never learned to program’s code looks like to a developer” it would make no sense, so why should we accept it in it’s current form?
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 😂
I’m sorry to tell you, friend, that your article does this too. You don’t explain what XAML is, for instance. Certain sentences almost read like the satire you posted: “how to do in C# code the things which are currently done in XAML (such as binding)”. You also tell the reader to “edit the relevant line” which doesn’t help a total beginner.
The fact of the matter is that writing for the lowest common denominator takes an incredible amount of time and writing skill. Most of us don’t have one, some don’t have both.
If you keep practicing technical writing, I’m sure you’ll get there eventually. Just keep in mind that most people do not want to be technical writers
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”
I’m sorry dude, but the other person is completely correct. You don’t explain a lot of things and then you use them as a basis for knowledge in the tutorial. For example Git and GitHub are both prerequisites that you don’t mention. Knowledge of layout is also a prereq. You don’t explain what binding is. There’s a ton of typos. You missed putting certain things in code blocks. You should every once in a while show the full class or file so the reader knows what they missed. There’s a lot that could be improved here.
Nobody is telling you off for this. You didn’t do anything wrong. Writing tutorials, even bad ones or mediocre ones is really appreciated. It’s hard to write a tutorial. It’s really hard to write a really good tutorial. Every tutorial I write I try to get feedback from colleagues to see what I could have done better, what isn’t clear. There’s always something.
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.
You mean all the things that have links to resources about them in the pre-requisite knowledge section? 😂
no, I mean the things I listed… Like Git, GitHub, and the rest
Now go read through the links in the pre-requisite section.
… I did. They’re literally links to download Visual Studio (nothing about git, github, views, literally anything besides downloading), a link to download .NET (same deal here), and a link to C# (once again, zero mention of git, github, etc.)
I think you must have started to add those in and forgot because there is absolutely no mention of them in your links.
Also, they’re not pre-requisites - it isn’t necessary to know how to use them, giving cloning the repo is optional - hence not listed as pre-requisites. See how that works?
From your article:
I have made the first commit at this point. The repo is at https://github.com/SmartmanApps/CSharpUI. This is preserved in the Master branch - all changes will be made in different branches so that you can swap between them to compare (though referring to the repo is optional - all the information you need is in this blog post).you mention commits. Knowing wtf you are talking about is a prerequisite to literally understanding the words you are typing. If it doesn’t matter then don’t mention it. You mention
repo. That requires knowing wtf a repository is. If it doesn’t matter don’t mention it. State “The code is at this link”, not “the repo is here, this is preserved in the Master [sic] branch” (which is one of your typos by the way). You then discuss swapping between branches. All of this requires understanding git. To anyone that knows nothing about programming your words are completely nonsense here. To any reader that sees your words “though referring to the repo is optional - all the information you need is in this blog post” they will think “then why did this author mention it?”
Knowledge of layout is also a prereq
No it isn’t. I specifically cover exactly that. I see you didn’t read it.
… yes it is dude. You literally didn’t cover it. The first mention of layouts is when you say
For those not familiar with this, normally a layout recalculation is done each time you add an element to the UI, but the batch begin and commit says that we are going to make a bunch of changes, and don't do any recalculations until we are done adding elementswhich is nonsense to someone that doesn’t know anything about layouts. You then proceed to say
Define our elements: Well, we get to cheat a bit here, since we're recreating an existing UI - we can just read through MainPage.xaml and see what's there.:-) The ScrollView and VerticalStackLayout are used to position the other elements on the screen, so that'll go in our "Assemble GUI" section - everything else are views.We can’t cheat and read through MainPage.xaml, you literally just had us delete it! Not only that but you said we don’t need to click on the link to the code and you said everything would be provided in the article! All of which are false at this point. Then you state “The ScrollView and VerticalStackLayout … everything else are views.”. WTF are
ScrollViewandVerticalStackLayoutandviews??? This requires prerequisite knowledge of how layouts work. This is not in any of the prerequisite links. It is not explained in the article.So not only do we need to actually be performing the actions in the article alongside you (meaning we can’t just read the tutorial to find the information we need), you’re forcing users to do the coding, and then you’re actually telling the users to use something you’ve had them delete! AND you expect them to know what views, layouts, and reflowing are.
Like Git, GitHub
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-requisites and 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…
(meaning we can’t just read the tutorial to find the information we need
You can if you’re already familiar with everything in the pre-requisites.
you’re forcing users to do the coding
How am I forcing them? They can just read it all if they want. Also, you know that’s why they are reading the blog in the first place, right? 😂
continued…
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
no you literally don’t and no, once again you seem to have maybe saved a draft somewhere that you are seeing prerequisite links that are not present in the published article. This is what we see
- https://visualstudio.microsoft.com/vs/
- https://dotnet.microsoft.com/en-us/download/dotnet
- https://learn.microsoft.com/en-us/dotnet/csharp/tour-of-csharp/tutorials/
The first link is a download link. The second link is a download link. The third link is a link to a single tutorial titled “Introduction to C#” and is made up of 6 sub-tutorials titled:
- Hello world and text
- Numbers in C#
- Tuples and types
- Branches and loops
- List collections
- Pattern matching
Not a single one of these tutorials mentions views, bindings, layouts, git, or even github. 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 really don’t want to do that. You can go search yourself since you think your tutorial is so perfect, you shouldn’t have any difficulty proving me wrong.
There’s a ton of typos.
says person not identifying any
I was trying to avoid writing a lengthy reply explaining every minute thing you’ve done wrong since that’s reductive and honestly rude. On top of that, I make plenty of mistakes myself so pointing out your grammar and typos is even worse. You’ve forced my hand though, here are some of your typos.
most commonly thiseither needs to be combined with the first sentence or needs to be capitalized(or Colors.cs if you must 😂)should be(or Colors.cs, if you must 😂)And ditto for Background, but set to whatever colour you want for the background. e.g. #FF000000 for black.should beAnd ditto for Background, but set to whatever colour you want for the background, e.g. #FF000000 for black.despite how it may appear,should beDespite how it may appear,Don't forge also thatshould beDon't forget also thatbatchbegin(); batchcommit();should beBatchBegin(); BatchCommit();what's there.:-)should bewhat's there. :-)So, now we just need to add our 2 properties.->So now we just need to add our 2 properties.where you have to change you code->where you have to change your code- you also switch between colour and color numerous times.
there’s more, but honestly this is incredibly tiring. You don’t need to admit anything. Just stop arguing about having a perfect tutorial. Nobody writes perfect tutorials. Claiming that you have is honestly ridiculous, especially when you’ve missed so much.
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)
no, but I also would never choose to do a tutorial on dev.to. Just because you chose to write a blog somewhere that makes your communication less effective doesn’t mean you aren’t responsible for your communication being less effective.
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.
this is very tiring. You never once show the full file in the article. In this comment you made here on Lemmy you have reaffirmed that you do not need to know or use Github to complete your tutorial so stating that you need to leave your article to see the full code is the exact opposite of what your tutorial has stated. I did read your tutorial, which is why I know you said those things.
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.
I’m very sorry you have to hear these criticisms in this way, but your tutorial is severely lacking. If a staff software engineer has trouble following your tutorial from the very beginning then there are things that can be improved. I stated those things nicely in my first comment and then you lashed out stating that I didn’t read your tutorial, even though I did. This comment here is the last I’m going to make on the subject. Your tutorial needs work. I’ve given you some things you can work on and you can either believe me (and the other comments from other users) or you can believe yourself and continue writing tutorials like this one.
no you literally don’t
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.
The second link is a download link
Ditto…
The third link is a link to a single tutorial titled “Introduction to C#”
Ditto
git, or even github
Still not a pre-requisite
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… 🙄
You have the patience of a saint for doing this. OP’s condescending attitude became too offputting for me to bother giving more detailed feedback
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). You say you usually delete this xaml file but I don’t need to do that. Why? What do I gain or lose? I thought I didn’t need to know xaml?
I read your entire tutorial. I’ve been in the industry for a while. I found it hard to read but mostly due to the sentence structure. I suppose if english isn’t your first language (it isn’t mine), that might explain it. I can give you more comprehensive feedback, if you’d like.
I know hearing constructive criticism is hard, but it is part of the learning process.
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.
Docs aren’t for everybody sometimes stuff is just complex and requires prior understanding. I guess that’s where more people can help FOSS projects, by writing more accessible docs and pre packaging stuff so it can be used by less technical people or someone who’s just starting out.
Agreed, maybe this writer could step in and volunteer their time instead of writing satire complaining about it.
How many dictionary lookups deep are people reasonably expected to go? Depending on the reader, there’s just some level of complexity that isn’t accessible any more. Add to that the diversity of mental models and approaches people take and a semantic structure intuitive to you just won’t work for someone else, no matter what words you use. Don’t get me wrong, you can’t cater to everyone and I’m not sure you should if you could.
I understand that your target audience are typically people already familiar with or at least invested in the subject matter, in which case leaning on a presumed funamental understanding and a willingness to fill gaps is sensible. You don’t want to bloat your docs by repeating things your most relevant readers already know.
In doing so, you “sacrifice” the accessibility for less versed people. In a perfect world, we wouldn’t have to choose and everyone would get an explanation suitable to their own level of understanding and background. Alas, our world imposes limits on our knowledge, abilities, time and energy. Readers and writers alike should be aware of those limits, both in themselves and in each other.
I feel like “Skill issue” understates the complexity of the combinatorics the diversity of human minds produces. It’s a human issue that might never be perfectly solvable. Your solution is good and appropriate, and that has to be enough.
My point is merely that we should be aware of the downsides of our choices and make that tradeoff consciously.
I think you’re spot on, and this is the reason I put “controversial” in front of it. I just felt like if we rewrote the blog post as a “What a writer who’s never learned to program’s code looks like to a developer” it would make no sense, so why should we accept it in it’s current form?
I think you’re spot on, and this is the reason I put “controversial” in front of it.
And I just can’t resist a good invitation for some discussion. Thank you for providing it!
I love the shit out of this. I can relate SO HARD to everything she wrote. It’s like most people don’t understand how to communicate with regular normal human beings
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
- Three Letter Acronym
Is… is it not standard to say “Three Letter Acronym (TLA)” the first time? What kind of monster?
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.
What kind of monster?
MS 😂 🤬
As a software developer with 10+ years in .Net. I don’t even bother with Microsoft documentation anymore, it’s often wrong or outdated and skips chunks that even senior devs need.
Wait until they learn about kazoopi tickling lmao they are gonna need some serious blizterop after that
Yes, you are not wrong here.
What I regularly have to deal with is about as bad. Big project, and every upgrade replaces one key element. They have never heard of backwards compatibility. If they don’t like a subset in their system, they replace it. Complete with different API calls, structures, and calling conventions. And they may document parts of it three versions later. If at all. Some documentation is basic Doxygen - just list the function parameters, and that’s it. I’ve seen cases where the documentation of the rather critical parameter “flags” was just the word “flags”. I’ve seen cases where the return value was documented only as “status”. Not even with a notion whether 0==success and 0!=failure or vice versa.
And no, it is not a closed application. They have an “extension” folder for user-supplied extensions. The problem: If it is not a core extension that has been updated with the main project, the first thing after an upgrade is finding out where your formerly working extension critical to your project now fails, because they just happened to think that the call interface for the boogaloo object need a complete overhaul. Maybe it needed an overhaul, but then at least keep the older interface alive for at least a few versions after documenting the new interface and marking the old one as deprecated.
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)
If it’s all gobbledygook to you, then you weren’t the target audience.
Most developers are writing for developers who have approximately the same skill level and knowledge. The vast majority of tutorials out there are definitely not aimed at beginners. They’re aimed at peers who know most of the same stuff, but want to broaden their horizons a little.
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. There are way too many tutorials that have a “rest of the owl” problem at some stage. I was trying to figure out how to do something today and I must have skimmed through 30 tutorials aimed at people roughly my skill level before I finally found one that explained the missing bit. That missing bit turned out to be pretty easy, but almost every thing I read just assumed people knew how to do that part, and focused in on all the wrong things.
As for actual tutorials for beginners, the biggest problem isn’t that they’re badly written. The biggest problem is that they don’t exist. But, to be fair, they’re actually really hard to write. Explaining things requires that you really understand them well. But, when you understand them well, it can be hard to put yourself in the shoes of someone who knows so little they don’t even know what questions to ask. Most computerey things are complicated enough that by the time you feel confident enough to write a tutorial, you’ve forgotten what it was like to be a beginner.
Most developers are writing for developers who have approximately the same skill level and knowledge
I think you’re correct about this, but I also think that’s part of the problem.
On the one hand you can have technical tutorials for technical people, but to your point assuming the audience has the same skill level and knowledge is actually a mistake - no two people share the same same life, so while it’s reasonable to assume a certain level of knowledge, you still need to consider that there may be gaps - small gaps but gaps all the same and that it’s worth being explicit about things to avoid ambiguity. A common pitfall I see in a lot of tutorials or guides is not being explicit about file paths (“just add this to the config folder” - which folder? Where?), or not correctly steering the user towards the relevant documentation about configuration values while still expecting them to insert some config file specific to their system, stuff like that.
The other end of the spectrum - the beginner, to your point might not be the target audience but a lot of people don’t realise that those folks exist. The absolute classic example I see of this is Linux for the Everyman - Lemmy is very big on promoting Linux and moving folks away from Windows/MacOS but 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. So they’re both not the target audience but expected to learn that stuff - and of course it doesn’t work and they stick to what they do know.
All this is to say, writing tutorials is a skill in itself and part of that skill is knowing who your target audience really is and knowing where your knowledge is his experience from working at something for so long or a basic level of understanding you expect a user to have.
“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.
The article is by what appears to be a career writer who implies that developers should be doing their job, too. Not to mention this is mostly in unpaid FOSS. The author’s method is tone deaf.
As for your response, while factually true, to your example: Lemmy users don’t care that you use Linux. Lemmy users care that you’re the type of person who will educate yourself enough to learn Linux.
Growth through learning, and part of that learning is figuring out the holes and filling them in. Heck, once Lemmy gets past that stage, we (and all those who took the plunge) will probably all move on to somewhere else.
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
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#
Beginner’s are the target audience for tutorials.
No, most of the time they’re not. And you don’t need to warn me that an “s” is coming.
If they had the same skill level and knowledge then they wouldn’t need a tutorial to begin with.
Note that I said “approximately”, not the identical level of skill and knowledge. It’s written by a fooblorts developer who uses migwed and ghai and is now looking to connect suwdo with ugfest. If you’re also a fooblorts developer who wants to connect suwdo with ugfest but you have no experience with that particular thing, then the tutorial is for you. It’s not for someone who has never used any of those technologies and doesn’t understand anything about them.
No they’re not
Ah, I can see you never write tutorials, nevermind then. You have no idea what you’re talking about.
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 😂
No idea what you’re talking about.
Beginners. It’s a plural, there’s no need for the apostrophe.
In other words, you are a beginner with that particular thing.
There’s a difference between “a beginner” and “someone who is very experienced but hasn’t done X”. The post was about a “non-developer”, not a “developer who understands and uses 90% of the same tech stack, but is looking to do something new related to it”.
It might be if that is what they are needing to learn.
If it were aimed at true beginners it would be written completely differently. A university teacher preparing a lecture about shakespeare doesn’t write the same lecture if their audience is a bunch of 5 year olds.
You know that’s what tutorials are for in the first place, right?
You know that’s not true, right?
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).
You sure that’s a tutorial and not the “about” page of half of github, where you have no fucking clue what the project is about?
I’m going to steal some of these words and use them in my future projects, and no one can stop me from doing that
Unironically, sounds simple. Unless there’s cmake in there, I always have some sort of trouble with that piece of garbage.
People say “RTFM” then you get to the manual and it’s this
Microsoft Manuals…
Basically Hello World using the win32 API. I believe I first encountered this before college, and it took actually professional dev experience to really understand it.
That is spot on. Usually you would expect the manual to be hit and miss when it comes to troubleshooting but Microsoft is consistently miss, skipping the important parts and details.
Microsofts documentation is also increasingly just outright wrong:
if you spend enough time looking up things about their newer products like M365, defender, or azure, especially when it comes to scripting related to those, there’s a ton of simply outdated info on the official docs that makes it really difficult to figure out why your setup isn’t doing what it’s supposed to.
from changed variable names, to missing functions, to unexplained buttons, etc., etc.
the newer docs are straight up trash!
you’re better off searching around for forum posts or whatever, than using the official docs…
If you are used to documentation like MS’s, then AI responses probably look more reasonable and useful. If AI results look better than your own docs you should feel really bad.
this is the part that’s really frustrating:
i sometimes feel forced to use chatGPT (duck.ai) to simply search for Microsoft things, because search engines only return SEO garbage with the exact same content spammed across like a million “tech tips for beginners” sites…and the docs, as established, are pretty useless…
keep in mind: i fucking hats “AI”.
making me use it makes me not have anything to do with whatever you’re selling.
it’s getting progressively more impossible to simply use MS products, because the information you need to use them is so hidden away!
combine those two things and ta-da: that’s why all my stuff at home is running linux now.
Amazon is no better. Go look up the correct parameter format required to set a compliance lock on an object in S3 via the API. Now try it yourself. Surprise!
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.
oh hey, that’s great! thank you!
Microsofts documentation is also increasingly just outright _wrong_:
There used to be a spot on joke about Microsoft documentation taking the piss out of the fact that it was always 100% accurate but at the same time pretty useless. That joke hasn’t been relevant for a while.
It’s so frustrating trying to find out how to do something in one of the admin centres for M365 and you find a Microsoft document with exactly what you need in it only to find out that the UI has changed and the steps don’t work now. Did they move it? Did they remove it? Who knows?
our admins are regularly straight up fighting against this bs!
“where the fuck has this fucked off to now?? it was right here last month?!”
so glad I’m not doing MS administration…
Also, requiring login.
Link 1: Pencil selection guide Link 2: Ovals vs. circles Link 3: Wings Link 4: Bird feet
Another problem is that people skim to the “most important bits” without knowing they’re skipping something important. Then some of those people complain how the manual is shit.
I guess it could be shit if it is way too verbose though.
Exactly what I was thinking. Like needing to understand a huge preamble just to do the Very Simple Thing. I just want to move on, not marry this Linux command.
Oh do grow up, frankly.
When I taught myself to program, there was no internet. You went and bought an enormous, 800 page book (usually written by Charles Petzold) and you hoped to Darwin something, anything would be understandable and lead you to move forward just a little bit.
If it’s worthwhile doing it’s hard.
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.
So maybe the tutorial the satirist was satirising just wasn’t quite aimed at the satirist.
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).
You recognize the feelings of the author and relate to them personally with Charles Petzold’s writing from back when, and say they need to grow up?
I think it’s a little reductive to say the author just wants everything to be easy.
Help me understand what the author is trying to say, please. It could be I’m missing something. It just reads to me like the author feels everybody else has a responsibility to somehow make complicated topics easy.
a responsibility to somehow make complicated topics easy
That’s what tutorials are for! 😂
Some topics are just complicated. If I write you a tutorial in fast Fourier transforms I can’t start the tutorial at 1+1=2.
I can’t start the tutorial at 1+1=2
But you can put it in the pre-requisites
Of course. But that wasn’t the complaint/satire of the satirist whose article we’re discussing.
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
Boop!
Me, a (mostly) backend developer, reading a Medium post on how to make your computer display a div using Awesome New Web Framework ™
Every front-end guide, despite modern HTML/CSS3/ES6+ being completely viable for building an entire web application without dependencies: “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!”
“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
I hear that. I was refactoring a codebase and they used a special library for tooltips. There are two tool tips on the entire site and the library uses its own perverse syntax.
I’ve never got into modern JS frameworks because they seem to be utterly insane. If you need all that to build a site, you need to work on your fundamentals.
I swear centering in css is intentionally left as a Lovecraftian mess simply so front end devs can feel superior
The issue here is that the author of that post, and potentially the fictional author of the thing being lampooned, are not drawing a distinction between a tutorial (or an explanation) and a how-to.
Either you want to get a task done, or you want to spend a lot longer learning how to work that out for yourself.
(Many tutorials will include small set of how-to-like instructions because emulating the actions of a master will improve one’s vocabulary of what can be done as well as how it is achieved.)
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.
People need to start putting in the effort. There is no such thing as learning for free.
RTFM is a form of self help that really should return to the modern zeitgeist
RTFM
The problem is the manuals which are written exactly as described in the post
For people to RTFM, you need clear and concise manuals for different groups of users.
It’s no use addressing most IT-related manuals without prerequisite knowledge and practical experience.
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#
I haven’t read the article but from the title and header alone, it already reminded me my experience of hosting Lemmy with 0 experience with self hosting. I learned how to start a docker and host a very basic stuff according to docker tutorial, no issue, but as i venture into hosting Lemmy where people keep saying “it’s very easy!”, i keep failing to do so because the tutorial itself written with a lot of jargon and also missing step (i remember running into a part where the tutorial asked me to just fill in necessary stuff. Which necessary stuff???), i eventually given up. Not sure if they rewrite it recently but i can’t be bother with these anymore.
The point here i assume is sometime dev with tons of experience expect people to know what they know, and then written stuff in heavy jargon for the basic tutorial. It’s a curse of knowledge.
“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.
If it’s an instruction to a dishwasher liquid, you better write it for first-graders.
Sure, if you write a documentation to some developer tools, use developer language.
But if it’s something you expect regular folk to use, think of how much more people could use it if they wouldn’t need to learn something entirely out of their field of expertise to use it.
You can make dishwashing liquid kit that would require extensive knowledge in organic chemistry to use. It would be cheap and darn simple to develop. You could release it today! You just…shouldn’t.
Remember people have their lives, and shouldn’t be forced to comprehend everything around them at a professional level. Many developers seem to forget about it A LOT somehow, shifting it to the user and saying “I’m done here”, sitting in the bubble of experts and treating users like stupid rats who can’t simply get a computer science degree to use their computer. As a food technologist, I recently developed a premix for home-baking of phenylalanine-free pastry, and 70% of the work was making it idiot-proof. It is true for any field, yet it is important. People can’t learn everything every time they need something, and it’s not their fault.
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
