Improve md-lint by forbidding you

[BridgeAR]

In our docs we try not to use you. If I remember correct, the md-linter actually has a possibility to add specific words to a black list. We might just add those in there as well to make sure they to not get back in.
The rule should only apply to ./docs/api/ *.md.

Some times it is just slipping through and we do not have to check for those explicitly anymore. What do others think?

[mmarchini]

+1

[jasnell]

Not just you, but first and second person (and third person singular) pronouns in general.

[BridgeAR]

@jasnell the issue with other pronouns is that they can also be used in a different context. And most pronouns were never used but we can definitely prohibit them as well.

[jasnell]

There are some exceptions to the rule, for sure. For instance, third person plural and third person genderless pronouns (e.g. they, them, etc) are generally always ok.

[fhinkel]

+1 to linting for you, he, she, his, and her.

[cjihrig]

Probably we and our as well.

[Trott]

I'm not sure how I feel about this. Our style guide says to avoid personal pronouns but stops well short of prohibiting them. By making it a lint rule, it implies that they are prohibited.

I guess the important question that is difficult to answer is: Is this likely to result in improved documentation?

[BridgeAR]

I personally do not have such an issue with you but it makes it easier for me as I tend to use it. With a lint rule I do not have to think about it anymore. And as far as I can tell that would probably not only be good for me but also for others. you is a common review comment in documentation PRs.

If the documentation is improved when not using it? I am not sure... I have no strong opinion and do not want to weight in.

[apapirovski]

Going to close this out given the lack of progress. Feel free to reopen if you feel strongly about it but this is probably better done as a PR.