iterative
docs: remove condescending/scary language
Continuation of #608
Here's a good article about this: https://dev.to/meeshkan/how-to-remove-condescending-language-from-documentation-4a5p#what
TL;DR: Presenting something as "extremely simple" (with the intention of selling a benefit) may result in the reader feeling intimidated, esp. if they don't find the topic simple.
Examples
simply
easy
basically
clearly
everyone knows
just
obviously
of course
As you/we can see, ...
It's well known
Some of these have legitimate uses like "just" as a quantifier e.g. just one thing vs. as a qualifier e.g. you can just xyz.
To fix: simply removing it works in most cases. If the intention was to emphasize something, be more descriptive e.g. now this can be easily done -> this feature aims to makes the process easier.
After running alex, I've quite a lot of occurrences of condescending language, there are too many files to change at once.
Some examples of files that contain condescending language are: checkout.md commit.md config.md destroy.md (and many more)
Committing changes to too many files at once might be hard to review. Should I list all the files here and then start fixing one by one, or should I propose multiple changes over a single PR, @jorgeorpinel ?
Nice tool @mformihir! Let's give #1396 some time first, since it's already trying to address this issue, and come back to your report after that. You may want to find something else to work on in the context of GSoD for now.
@mformihir only if you can find condescending language that's not included among these changes, which are already in progress by another person: https://github.com/iterative/dvc.org/pull/1396/files
Other than that any issue you find that doesn't seem to be in progress by anyone else is fair game, no need to wait for my confirmation if you're reasonably certain. Just send a PR 🙂
Also, no need for a huge contribution. A small PR would be best, and once it's merged we can work on other small ones. the point here is to see how we collaborate (in the context of the GSoD applications). Thanks
@mformihir actually! Yes, please take on this issue as it has been dropped by the previous person attempting to address it. You can probably start by copying some of the changes in https://github.com/iterative/dvc.org/pull/1396/files (but please review all the comments in that PR because some changes weren't correct).
And again, no need for a huge contribution. A small PR would be best, even if it only addresses this issue partially. Thanks
No need to include blogs. Ideally DevRel should also adhere to this but they should decide whether to revisit old posts for this (cc @jendefig). Also, some instances of potentially "condescending" words are legitimate i.e. when descriptive (instead of qualitative) e.g. "... done just once" is OK, "just do that" not so much.
But yes we never finished reviewing the docs for this, only the cmd ref was done for now. However in recent content we review (at least myself) we've kept these kinds of phrases out so there shouldn't be too many newer instances.
Want to take the user guide @iesahin ?
Cc @tapadipti @daavoo for Studio/ DVCLive, respectively: up to you whether it's worth it reviewing existing content of just keep in mind for the future.
idk about the examples listed in the OP as being "scary" but they are definitely too verbose/distracting for docs IMO. Make things sound like an informal blog rather than a concise user-oriented give-me-a-solution-to-my-problem-now style.
