Add second person rule

[ChrisChinchilla]

No description provided.

[jdkato]

Shouldn't this use the existence extension point?

Use second person ("you") when speaking to or about the reader. Authors can refer to themselves in the first person ("I" in single-author articles or "we" in multiple-author articles) but should keep the focus on the reader.

This seems to imply that we should ensure instances of "I" or "we" are only in reference to the author(s) rather than checking that "you" and "we" aren't used together.

[gaurav-nelson]

I agree, we should use existence to check the usage of "I" and "we".

[ChrisChinchilla]

Hmm, my reasoning was for more of a check on consistency, so the predominance of using "I" in a doc, instead of "we". If we just check for existence, then it's not so useful without context, which is not something Vale can do.

Unless I am misunderstanding what you both mean, I kind of see how both could do the same, but the consistency part was my reasoning.

[jdkato]

I think I understand your intent better now. The part of the description that says

"I" in single-author articles or "we" in multiple-author articles

could indeed be a candidate for consistency since an article can't be both single- and multi-author. (As written, though, the rule involves "we" and "you"; not "we" and "I" ...?)

If we just check for existence, then it's not so useful without context, which is not something Vale can do.

IMO, this is an ideal case for a sub-error level rule (which can be selectively disabled): It alerts writers to the fact that, according to the style guide, that they're only supposed to use "I" and "we" in certain contexts without explicitly telling them that they're doing something "wrong" (which they might not be). The alternative (limiting ourselves to precise, error-candidate rules), means we'll end up covering much less of the style guide.

---

Basically, from my understanding of the discussion so far, we're looking at the two following rules:

extends: consistency
message: 'Use "I" in single-author articles or "we" in multiple-author articles.'
level: error
link: https://www.ibm.com/developerworks/library/styleguidelines/#N10050
either:
  I: we 

and

extends: existence
message: 'Only use "%s" when referring to yourself, the author(s).'
level: warning
link: https://www.ibm.com/developerworks/library/styleguidelines/#N10050
tokens:
    - I
    - we

Does this seem right?

[ChrisChinchilla]

Huh, interesting, I think I need to try implementing to see if it matches, but makes sense.

Is "sub-error level rule" an actual thing @jdkato or did you just use that as a description?

[jdkato]

By "sub-error" I meant warning or suggestion, which don't result in non-zero return codes.

[ChrisChinchilla]

By "sub-error" I meant warning or suggestion, which don't result in non-zero return codes.

Ah ha, OK, yes, I tend to err on that side of caution for "warnings" anyway.

[ChrisChinchilla]

OK, reminded to get back to this PR