I don't share the author's POV describing this sort of thing as "infuriating" or anything else that dramatic, but the before-and-after documentation example was definitely more readable and clear (I've never worked with rails [ruby?]).
So I support the overall premise here. It's nice to read documentation that is at least verbose enough to give you additional keywords to search with if you need more help, and I do feel a little bit more respected as a user when it feels like someone took time and care to write the docs with juniors in mind.
I think that a lot of the tutorials available on Digital Ocean are actually good examples of this; though they're not "docs" per se.
> a lot of the tutorials available on Digital Ocean are actually good examples of this
Second this (although the qualities of DO’s tutorials can vary greatly). Indeed, their “Technical Writing Guidelines” [1] agree with the author:
> We avoid words like "simple,” "straightforward,” “easy,” “simply,” “obviously,” and “just,” as these words make assumptions about the reader’s knowledge. While authors use these words to encourage and motivate readers to push through challenging topics, they often have the opposite effect; a reader who hears that something is “easy” may be frustrated when they encounter an issue. Instead, we encourage our readers by providing the explanations they need to be successful.
So I support the overall premise here. It's nice to read documentation that is at least verbose enough to give you additional keywords to search with if you need more help, and I do feel a little bit more respected as a user when it feels like someone took time and care to write the docs with juniors in mind.
I think that a lot of the tutorials available on Digital Ocean are actually good examples of this; though they're not "docs" per se.