As a developer, that is also how I read tutorials written by other developers.
Reminds me of one of my favourite Xkcd.
Although I guess we are more in this one, really.I’m really impressed by people who can write stuff that makes kinda sense, while being complete gibberish. Very funny and y’all need to remember where you are.
as of right now the second xkcd you linked is in an identical format to the newest xkcd. Not relevant to the post, just think it’s cool
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!
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
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.
-
My God y’all can’t just let a joke be a joke if there’s an option for you to be correct instead, LMAO
Edit: I just scrolled through all the comments and saw that the large majority of the replies here are very long, multi-paragraph comments. Y’all ok? Did this post touch a nerve with some of you? LMFAO
Actually!
I went to the comments expecting some more jokes but found multiple dissertations instead wtf.
Yooo, seriousely whats going on?? Hahaha
At least once in their life, every tech person should be forced to teach someone like my mum how to use a piece of technology.
That will very quickly change your perspective on what counts as user friendly.
Pretty sure every tech person at some point or another has had to do exactly that. And not just their mom, but their dad, and their extended family, and their parent’s friends who have a random problem, etc
And why? Because none of them can read the fucking manual! And you’ll say they don’t try, but many of them have tried. Once. And all they learned was that it wouldn’t do them any good.
I think the issue is that you need to understand who your users actually are. Documentation for a library intended to be used by a reasonably competent software engineer is going to have different requirements vs documentation for a cli utility aimed at Arch btw Linux users vs documentation for a program to help Grandma organize family photos.
If you throw a terminal command at Grandma she’s going to panic and call her grandchild. If you put instructions for extracting a tarball in your library docs the programmer is going to get bored and skip ahead.
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?
People say “RTFM” then you get to the manual and it’s this
Microsoft Manuals…
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.
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.
I think the blogger is more technical than they let on:
- understands how to write footnotes
- structures lists correctly
- runs their own blog with custom domain name.
I’ve known programmers struggle with markdown.
Well that’s because markdown is for documentation, and we all know programmers don’t know how to write documentation.
Documentation goes in the commit message.
That way you know when it was correct, because the next commit immediately makes it stale.
This reminds me of the “WHY IS THERE CODE??? MAKE A FUCKING .EXE FILE AND GIVE IT TO ME” post that blew up a while back
https://copypastatext.com/i-am-new-to-github-and-i-have-lots-to-say/
And both boil down to
-
guides can be prioritized more in some projects and it might be in the best interest of the creators to do that
-
different guides are written for different audiences, sometimes a guide isn’t meant for the average person
-
I envy some people’s ability to come up with nonsense words.
The more advanced the level of knowledge on something the more foundation knowledge somebody has to have to even begin to understand things at that level.
It would be pretty insane to in a tutorial for something at a higher level of expertise, include all the foundational knowledge to get to that level of expertise so that an absolute beginner can understand what’s going on.
Imagine if you were trying to explain something Mathematical that required using Integrals and you started by “There this symbol, ‘1’ which represents a single item, and if you bring another single item, this is calling addition - for which we use the symbol ‘+’ and the count of entities when you have one single entity and ‘added’ another single entity is represented by the symbol ‘2’. There is also the concept of equality, which means two matematical things represent the same and for which the symbol we use is ‘=’ - writting this with Mathematical symbols, ‘1 + 1 = 2’” and built the explanation up from there all the way to Integrals before you could even start to explain what you wanted to explain in the first place.
That said, people can put it in “recipe” format - a set of steps to be blindly followed without understanding - but even there you have some minimal foundational knowlegde required - consider a cooking recipe: have you ever seen any that explains how does one weight ingredients or what is “boiling” or “baking”?
So even IT “recipes” especially designed so that those with a much lower level of expertise than the one required to actually understand what’s going on have some foundational knowledge required to actually execute the steps of the recipe.
Last but not least I get the impression that most people who go to the trouble of writting about how to do something prefere to do explanations rather than recipes, because there’s some enjoyment in teaching about something to others, which you get when you explain it but seldom from merely providing a list of steps for others to blindly follow without understanding.
So, if one wants to do something way above the level of expertise one has, look for “recipe” style things rather than explanations - the foundational expertise required to execute recipes is way lower than the one required to undertand explanations - and expect that there are fewer recipes out there than explanations. Further, if you don’t understand what’s in a recipe then your expertise is below even the base level of that recipe (for example, if somebody writes “enter so and so in the command prompt” and you have no fucking clue what a “command prompt” is, you don’t meet the base requirements to even blindly follow the recipe), so either seek recipes with an even lower base level or try and learn those base elements.
Further, don’t even try and understand the recipe if your expertise level is well below what you’re trying to achieve: sorry but you’re not going to get IT’s “Integrals” stuff if your expertise is at the level of understanding “multiplication”.
It would be pretty insane to in a tutorial for something at a higher level of expertise, include all the foundational knowledge to get to that level of expertise
You don’t need to include it all. You just need to mention it as pre-requisite knowledge, and link to resources about it for those who don’t have that knowledge. See Creating MAUI UI’s in C#
I get the impression that most people who go to the trouble of writting about how to do something prefere to do explanations rather than recipes
Good documentation includes both. i.e. step-by-step guide, with explanations. See above.
so either seek recipes with an even lower base level
All documentation should cater to all levels. See above.
For “all documentation” to “cater to all levels” it would have to explain to people “how do you use a keyboard” and everything from there upwards, because there are people at that level hence it’s part of “all levels”.
I mean the your own example of good documentation starts with an intro of “goals” saying:
“Visual Studio (VS) does not (currently) provide a blank .NET Multi-platform Application User Interface (MAUI) template which is in C# only. In this post we shall cover how to modify your new MAUI solution to get rid of the XAML, as well as cover how to do in C# code the things which are currently done in XAML (such as binding). We shall also briefly touch on some of the advantages of doing this.”
For 99% of people almost all that is about as understandable as Greek (expect for Greek people, for whom it’s about as understandable as Chinese).
I mean, 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).
I mean, if IT knowledge was a scale of 1 to 10 with 10 the greatest, you’re basically thinking it’s “catering to all levels” when an explanation for something that is level 8 knowledge (advanced programming) has a baseline required level of 7 (programming). I mean, throw this at somebody that “knows how to use Excel” which is maybe level 4 and they’ll be totally lost, much less somebody who only knows how to check their e-mail using a browser without even properly understanding the concept of "browser (like my father) which is maybe level 2 (he can actually use a mouse and keyboard, otherwise I would’ve said level 1).
I think you’re so way beyond the average person in your expertise in this domain that you don’t even begin to suspect just how little of our domain the average person knows compared to an mere programmer.
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 😂
Cool but nobody’s about to link to prerequisite information like typing on a keyboard. Same for math, a book focusing on integration isn’t going to say “read this book for the basics of addition btw”.
And why should one even cater to that? If a person is interested enough they can just… look up the things they don’t understand, that’s not exactly hard
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.
I think your tutorial depends too much on your editor UI. It reminds me of those tutorials (often written by Microsoft) where the IDE has changed enough to break the tutorial. This made the tutorial completely useless, because none of them would explain what I actually needed: the magic thing their IDE did in terms of essentials (text files, basic commands), so I could reproduce the effect.
This is different in the unix world, which favors tool-agnostic approaches in terms of text files & basic commands. Even as tooling & technology changes, I can usually look up the meaning of the text & those commands to update them.
That’s the most important I think: not the answer itself, but where the answer comes from, so I can go back there when I need to.
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.
It’s not a bug, it’s a feature
It’s a bad one: if I’m unable to get that version of your IDE, the tutorial becomes useless. If it had stuck to programming essentials like the source code & configuration files, then it’d have enduring value as the reader could understand without unnecessary concealment of basic information dependent on an IDE.
no bloat from going through everything twice (once for VS, once for VS Code)
Not implied: the tutorial would properly focus on the programming without IDE complications as it shows the files generated & dependencies linked. (eg, “I did this in my IDE: here’s what it did”.) The reader could in principle use any text editor. It’s not an IDE tutorial.
Microsoft hasn’t written a tutorial for this topic, at all, right?
And you made another Microsoft-grade tutorial: that’s not a compliment.
if I’m unable to get that version of your IDE, the tutorial becomes useless.
No it doesn’t. Clicking on the link gives you the latest version, which obviously is above the minimum version.
without unnecessary concealment of basic information dependent on an IDE
Haven’t concealed anything - it’s there in the pre-requisites
“I did this in my IDE: here’s what it did”
I have many screenshots showing exactly that.
The reader could in principle use any text editor
No they can’t. Several times I cover the Intellisense options which make it easy. This isn’t available in a text editor, hence the pre-requisite of using Visual Studio if you want to follow this blog.
It’s not an IDE tutorial
It’s not meant to be. It covers what you need to know to do what I have done in the blog.
And you made another Microsoft-grade tutorial
Nope! They don’t include pre-requisites at all, never mind links to them, never mind step-by-step processes with screenshots, etc.
I Prefer a playbook to a recipe card. The playbook should spell out the goal and the 'why’s of the steps. Because if the process throws an error due to upgraded code etc, then you can be stuck at step one with no path forward. With some playbook annotation you at least know expected out come and why you are running a command etc.
When I have gone to docker hub I always view multiple images and see what their writeup is like. Some just assume you 100% know all dockers subtleties, some have a one liner, but there will be a helpfull soul who spells out what steps to do, and what the best options to set etc. Like a mini tutorial.
I find the mini tutorial to be widely beneficial, because it removes the blackbox nature, and gives new onboarding users a chance to grasp the concepts docker works with.
It’s like the difference between going to a mechanic that has you sit by the coffee machine in the office while they change your brakes and they come back and say “I swapped the new pads in”, vs them pulling up a chair in the shop and explaining the process “here I’m wirebrushing the back of the wheel and the hub, to make sure when it goes back on there is no corrosion debris stopping a parallel fit…now I’m applying high temp grease so that the hub and wheel don’t sieze together from corrosion and make next removal easy”
The info is probably useless to a seasoned mechanic that had a broken hand so had somebody else do their brake work, but highly useful to the next gen of person that can absorb it and know whats and whys.
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.
I feel that way about pretty much anything these days. The sheer volume of options and the complexity of everything is simply exhausting. Even finding food for my cat is overwhelming.
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
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!
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!).
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.
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.
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
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 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? 😂
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.
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.
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.
