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

3 days ago

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

fmstrat@lemmy.nowsci.com · edit-2 3 days ago

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.

Flamekebab@piefed.social · 2 days ago

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!

BCsven@lemmy.ca · 2 days ago

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

fmstrat@lemmy.nowsci.com · 2 days ago

Oh man, this I do hate. If you have terminology in your app, that is not a standard, please, please define it.

2 days ago

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!).

2 days ago

deleted by creator

ZeroOne@lemmy.world · 2 days ago

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.

CheerfulPassionFruit@lemmy.world · 2 days ago

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.

fmstrat@lemmy.nowsci.com · 2 days ago

Agreed, maybe this writer could step in and volunteer their time instead of writing satire complaining about it.

luciferofastora@feddit.org · 2 days ago

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.

fmstrat@lemmy.nowsci.com · 2 days ago

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?

luciferofastora@feddit.org · 2 days ago

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!

2 days ago

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.

r4venw@sh.itjust.works · 2 days ago

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

2 days ago

I’m sorry to tell you, friend, that your article does this too

Nope.

You don’t explain what XAML is, for instance

You know the article is about how to write a page and NOT use XAML, right?? 😂 If you don’t know what it is then you don’t need to (hence why I point out that it isn’t pre-requisite knowledge). If you do know what it is then that’s probably what brought you to my page to begin with - stop using it! 😂

Certain sentences almost read like the satire you posted:

Now read the links provided in the pre-requisite knowledge. You’re the second person who thinks people learn things by reading the first paragraph only.

You also tell the reader to “edit the relevant line” which doesn’t help a total beginner

Now read the links in the pre-requisite knowledge, clone the repo, follow the instructions up to that point in the article, and guess which line you’re on! 😂

I’m sure you’ll get there eventually

It’s there already, if you had just bothered reading it all and following the instructions, instead of just criticising without even trying it

Just keep in mind that most people do not want to be technical writers

Probably because of people like you who criticise them without even trying to follow the directions to begin with. I’m guessing you also submit issues which say “It doesn’t work. Please fix”

r4venw@sh.itjust.works · 2 days ago

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.

2 days ago

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.

tyler@programming.dev · 2 days ago

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.

edit-2 1 day ago

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.

tyler@programming.dev · 2 days ago

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

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 this either 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 be And ditto for Background, but set to whatever colour you want for the background, e.g. #FF000000 for black.
despite how it may appear, should be Despite how it may appear,
Don't forge also that should be Don't forget also that
batchbegin(); batchcommit(); should be BatchBegin(); BatchCommit();
what's there.:-) should be what'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.

r4venw@sh.itjust.works · 2 days ago

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

tyler@programming.dev · 1 day ago

Nah I just didn’t want anyone coming by and believing OP’s bullshit. They’ve made it abundantly clear with their comments now that they don’t actually know how to write a tutorial so it’s no longer necessary for me to respond. They even claimed that because they linked to the VS website that means that anything listed anywhere on that site is a prerequisite which is so hilariously backwards as to be moronic. Like they posted pictures stating that the headers are links that indicate there’s prerequisites. 😑

2 days ago

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… 🙄

tyler@programming.dev · 2 days ago

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 elements

which 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 ScrollView and VerticalStackLayout and views??? 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.

edit-2 1 day ago

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? 😂

fmstrat@lemmy.nowsci.com · 2 days ago

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?

2 days ago

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 😂