Testing language style

[Elchi3]

Let me know if this is too opinionated, but I have some thoughts regarding writing style in documentation and I think it would help me to get some of this tested automatically when reviewing.
I think these things should be warnings, as you still have to look at the context and then judge them.

• There should be no "can't", "won't", "don't". Instead "cannot", "will not", "do not".
• There should be no "obvious(ly)", "simple/simply", "easily", "clearly", or "just" (by saying these words nothing gets simpler and we do not know the reader's abilities)
• There should be no "I" and "we".
• Please not "Javascript", it is "JavaScript" and "ECMAScript".
• MDN style guide is to not capitalize headlines, not "Querying Available Extensions", but "Querying available extensions".
• Don't use "he" or "she", but "they" for neutral gender language!

There is likely more, but this is a start. Would like to hear opinions if it makes sense to add these things (or a subset) as tests.

[SebastianZ]

• There should be no "can't", "won't", "don't". Instead "cannot", "will not", "do not".

What about "shouldn't" and "hasn't"?
I think everybody understands "can't", "won't", and "don't" and while writing I often use the abbreviations, so I don't (<- 😃) see a strong reason to change that. Also, note that the writing style guide explicitly allows the use of contractions.
I don't have a strong opinion about disallowing contractions, though, so I'd like to hear other opinions about that.

• There should be no "obvious(ly)", "simple/simply", "easily", "clearly", or "just" (by saying these words nothing gets simpler and we do not know the reader's abilities)

Sounds reasonable. However, I think that "simple" may appear in some descriptions for valid reasons, e.g. at https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS/API/Simple_Push_API.

• There should be no "I" and "we".

Agree. (Note that the style guide itself uses "we" at some places.)

• Please not "Javascript", it is "JavaScript" and "ECMAScript".

Yes! Also other expressions like "HTML" instead of "html" for example.

• MDN style guide is to not capitalize headlines, not "Querying Available Extensions", but "Querying available extensions".

Good point. We may need to add a whitelist for words where capitalization is allowed or needed, though, like for "JavaScript", "Web" (looks like there's no conclusion on that), "Firefox", etc.

• Don't use "he" or "she", but "they" for neutral gender language!

Clear thing.

Maybe we should also check other points of the style guide. Here are some more of them:

• Latin abbreviations should be correctly abbreviated and used.
• Use sentence-style capitalization for keyboard shortcuts.
• Use proper hyphenation for "email", "re-" and "co-".
• Correctly format dates and numbers. (Though the rule about setting a comma only on five-digit numbers looks strange to me.)
• Use "element" instead of "tag" when referring to an HTML or XML element and wrap it into arrow brackets (or use the appropriate macros).

Sebastian

[Elchi3]

CC'ing more people. @teoli2003, @wbamberg, @chrisdavidmills, @a2sheppy, @jmswisher, @markgif.

I would appreciate thoughts on whether things that are mentioned above make sense to be tested as part of this add-on, so that our writing style is enforced more when doing reviews.

[wbamberg]

Since you asked...I agree with all your points in the original comment except the first (I think disallowing contractions can result in much more stilted language). But with the exception of things are almost always actual errors (in your list "Javascript" is the only one I can see, and maybe he/she) I don't like the idea of baking these checks into a tool, since there are many exceptions and subtleties here. I'm arrogant enough about this to think that I'm more likely to be right than the tool, and I would be less likely to use the tool if it constantly nagged me about "problems" that I didn't see as problems.

(More generally, although I'm quite opinionated about style, I try not to impose my opinions on other people too much. I think a pedantic adherence to an overly-prescriptive style guide leads to a bland homogeneity of writing.)

[SebastianZ]

I want to add that almost all of the points above only apply to English articles, so those tests should only be executed there and not shown in other languages.

Sebastian

[a2sheppy]

I agree that disallowing contractions is a mistake. I encourage their
use since writing without them reads like it was written by a robot.

---

From: wbamberg
Sent: Thursday, Feb 25, 2016 12:08:37 PM EST
To: Elchi3/mdn-doc-tests
Cc: Eric Shepherd
Subject: [mdn-doc-tests] Testing language style (#128)

Since you asked...I agree with all your points in the original comment
except the first (I think disallowing contractions can result in much
more stilted language). But with the exception of things are are
almost always actual errors (in your list "Javascript" is the only one
I can see, and maybe he/she) I don't like the idea of baking these
checks into a tool, since there are many exceptions and subtleties
here. I'm arrogant enough about this to think that I'm more likely to
be right than the tool, and I would be less likely to use the tool if
it constantly nagged me about "problems" that I didn't see as problems.

[a2sheppy]

I also disagree with disallowing "we". I think it's a good pronoun to use in tutorials, where you want the reader to feel as if they're on a guided tour "with MDN" as if it were a person. It's also difficult to write authorlessly when writing tutorials, and "I" is indeed to be avoided as it implies a certain "I know something you don't attitude."

However, detecting "I" as a pronoun can be tricky, as it could in theory be a variable name or a Roman numeral. Neither of those should be true, but they could be...

I suggest having a "style guide" checker, which looks for stuff specific to our style guide, then perhaps a separate grammar checker which uses an online grammar checking tool or a library to offer grammar suggestions (but not errors; grammar checkers are iffy if not used wisely).

[markgif]

Hi Elchi3!! I mostly agree with you except I don't mind a few contractions (don't etc.). But I suppose it could be that non-native English speakers find contractions more difficult than fully spelling out the words. Just a guess.

I kind of agree with sheppy on "we", in that limited use.

[SebastianZ]

But I suppose it could be that non-native English speakers find contractions more difficult than fully spelling out the words.

Well, at least in Germany we learn the contractions at school together with their full-spelled equivalent. I don't know how it is in other countries, but I assume most of them should be known.

However, detecting "I" as a pronoun can be tricky, as it could in theory be a variable name or a Roman numeral. Neither of those should be true, but they could be...

Then the question is, whether we want to accept false positives or not.
Variable names could easily be excluded, if we say that code samples are excluded from checking.

Sebastian

[chrisdavidmills]

I agree with sheppy about "we" and contractions.

1. If we are running a community site, we want to be careful about robotizing/homogenizing the language too much.
2. I really like using "we" in tutorials to make it seem like "we are knowledgeable peers going on a journey together to learn something", rather than "I the teacher know way more than you, the student, and am going to teach it to you." The former seems way less patronizing and more comforting, especially to beginners.

I agree with Florian's other points.

[chrisdavidmills]

"Use "element" instead of "tag" when referring to an HTML or XML element and wrap it into arrow brackets (or use the appropriate macros)."

Yes. This is something I am pretty picky about. It is surprising how many people use "tag" and "element" interchangeably.

[Elchi3]

Thanks everyone! Great and fruitful discussion :)

Here is my summary or "intent to implement" for a first iteration:

If you check against an en-US article, let the test suite emit...

• a warning if the page contains the words "obvious(ly)", "simply", "easily", "clearly", or "just".
• a warning if the page contains the word "I" (the pronoun).
• a warning if the page contains the word "tag(s)" in the context of HTML/SVG/XML/MathML elements.
• an error if the page contains wrong capitalization for the words "JavaScript", "ECMAScript", "HTML", "Firefox", "SpiderMonkey" ... (likely to be extended)
• an error if the page contains the words: "he", "she", "whitelist" or "blacklist".

We will likely identify more things regarding language style (and discuss them), but I think these points are a good start. If there is no disagreement, we can open issues for the above list.

[SebastianZ]

If there is no disagreement, we can open issues for the above list.

We may open several issues for the points above, though I believe they should all be implemented under one test named Language style. If we agree on that, we'll need to fix issue #52 first, though.

Sebastian

[a2sheppy]

I wonder if it would be worth investigating a way to use a mechanism for
maintaining these rules to check independently from the code, so that
they could be loaded from a secondary location similarly to how the
"database"-driven macros work. If that could be done even for some of
these language usage tests, it would make maintenance much easier and
more flexible.

---

From: Florian Scholz
Sent: Monday, Feb 29, 2016 8:05:09 AM EST
To: Elchi3/mdn-doc-tests
Cc: Eric Shepherd
Subject: [mdn-doc-tests] Testing language style (#128)

• a warning if the page contains the words "obvious(ly)", "simply",
  "easily", "clearly", or "just".
• a warning if the page contains the word "I" (the pronoun).
• a warning if the page contains the word "tag(s)" in the context of
  HTML/SVG/XML/MathML elements.
• an error if the page contains wrong capitalization for the words
  "JavaScript", "ECMAScript", "HTML", "Firefox", "SpiderMonkey" ...
  (likely to be extended)
• an error if the page contains the words: "he", "she", "whitelist
  http://english.stackexchange.com/questions/51088/alternative-term-to-blacklist-and-whitelist"
  or "blacklist
  https://twitter.com/kthomas901/status/656157231365423104".

-- Sheppy

[SebastianZ]

Requesting these tests from a server might be an improvement in the future. Though, requesting the tests externally also implies some security risk and is slower. Furthermore I expect those tests to change relatively seldomly once they are implemented. Or is the writing style guide changing that frequently?

Sebastian

[a2sheppy]

You're right, the tests shouldn't change often. But while the style
guide doesn't change much, the list of "good" words may, as new
technologies are invented and named, change. That's why I was thinking
having rules be more editable would be good.

Probably not worth the effort, but I needed time to work that out. :)

---

From: Sebastian Zartner
Sent: Tuesday, Mar 1, 2016 2:16:16 AM EST
To: Elchi3/mdn-doc-tests
Cc: Eric Shepherd
Subject: [mdn-doc-tests] Testing language style (#128)

Requesting these tests from a server might be an improvement in the
future. Though, requesting the tests externally also implies some
security risk and is slower. Furthermore I expect those tests to
change relatively seldomly once they are implemented. Or is the
writing style guide changing that frequently?

-- Sheppy

[jmswisher]

Perhaps a later iteration could allow for custom rules. For example, non-native speakers might want to be warned about certain problematic usages, while native speakers might not want to be bothered, as they trust themselves to know better than a tool about such things.

[a2sheppy]

Agreed; we can contemplate customizations later on. Focusing for now on
the core stuff is the important thing for now, you're right.

---

From: Janet Swisher
Sent: Tuesday, Mar 1, 2016 1:19:03 PM EST
To: Elchi3/mdn-doc-tests
Cc: Eric Shepherd
Subject: [mdn-doc-tests] Testing language style (#128)

Perhaps a later iteration could allow for custom rules. For example,
non-native speakers might want to be warned about certain problematic
usages, while native speakers might not want to be bothered, as they
trust themselves to know better than a tool about such things.

-- Sheppy

[Elchi3]

Re-filed as mdn/doc-linter-rules#19