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 13 points 1 week ago (5 children)

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!

[–] SmartmanApps@programming.dev 4 points 1 week 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!).

load more comments (4 replies)

load more comments (24 replies)