Repository navigation
Improve md-lint by forbidding you #19030
Description
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?
Activity
mmarchini commentedon Feb 27, 2018
+1
jasnell commentedon Feb 27, 2018
Not just
you, but first and second person (and third person singular) pronouns in general.BridgeAR commentedon Feb 27, 2018
@jasnell the issue with other pronouns is that
theycan also be used in a different context. And most pronouns were never used but we can definitely prohibit them as well.jasnell commentedon Feb 27, 2018
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 commentedon Feb 28, 2018
+1 to linting for
you,he,she,his, andher.cjihrig commentedon Feb 28, 2018
Probably
weandouras well.Trott commentedon Mar 7, 2018
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 commentedon Mar 7, 2018
I personally do not have such an issue with
youbut 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.youis 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 commentedon Oct 26, 2018
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.