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.

[–] SmartmanApps@programming.dev 0 points 6 days ago (14 children)

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.

[–] fmstrat@lemmy.nowsci.com 2 points 6 days ago (1 children)

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?

[–] SmartmanApps@programming.dev 0 points 6 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 😂

load more comments (12 replies)

load more comments (23 replies)