Edit documentation for consistency

[philwebb]

With #27759 @Buzzardo applied an editing pass to the actuator documentation. There are quite a few patterns that emerged from that set that we should try and adopt going forward. We can update this epic with items as we identify them and create distinct issues/commits for each one when we apply it.

• Use consistent case for 'Servlet' and 'Filter' in documentation #27896
• Replace "via" in documentation and use "over" or "through" instead #33878
• We should replace "refer" and "check out" with "see".
• Expand English contractions from the documentation #28064
• Expand English contractions from the documentation #28064
• "will enable" can be replaced with "enables" #28567
• And See "<<... references should use lowercase contents.
• Table with descriptions should start with "The...". For example, "The color of the sky" rather than "Color of the sky".
• We should when possible change "deny" to "prevent".
• We need to check if we said "less" when we meant "fewer" – none found
• Replace latin 'i.e' and 'e.g.' in the documentation #28141
• Use a consistent quote style of "`thing`"
• Use "as the following example shows" for example lead-in
• Replace "etc" in reference documentation #28497
• Replace "check out" with more formal language #28503
• Replace "refer to" with "see" #28537

[Buzzardo]

In a couple of cases, you have identified specific examples of wider rules. Expanding "don't" to "do not" and "it's to "it is" are instances of the broader rule to not use contractions. That is, an apostrophe should always indicate a possessive. (That one comes from formal academic writing, which has had a large influence on technical writing over the years.)

"e.g." to "for example" and "i.e." to "that is" and "via" to "through" are all examples of avoiding Latin. More than half the population confuse "e.g." and "i.e.". Similarly, most people couldn't tell you what "via" actually means. (It's Latin for "through." I studied Latin in college.) Also, screen readers sometimes do awful things to them, most notably rendering "e.g." as "egg."

"Will enable" is an instance of the broader rule to never use "will" or otherwise use the future tense. The better reason to do that is consistency. Keeping everything in the simple present tense is more consistent. Doing so often makes sentences shorter, too. The worse reason is one of those funny-sad stories. When I worked at GE, we got sued because we had used "will" in a document. Some twit sued us because we made a promise we didn't keep. The case got tossed out, but GE had to pay lawyers to deal with it.

Aside from consistency, all three of these editing rules have another reason behind them, too: English as a second language. Consistency is itself a huge help to people who may not have a strong grasp of English and have to read things multiple times to get the meaning. Avoiding Latin (and other languages that aren't English) keeps yet another language out of the mix. Expanding contractions avoids potential misreadings. Keeping the tense in the simple present avoids parsing of more than one tense.

Finally, many cultures expect a greater level of formality than native English speakers expect. If our audience were solely native English speakers, we could be a lot more "loose" in our writing. However, the Chinese (especially) and other asian cultures expect formal structures in their technical writing. To them, it is official writing, and they believe it should be written that way. They are more comfortable with more formal writing, and we should meet them where they are, so long as doing so does not cause other troubles (and all these other rules have other good reasons behind them, too).

[snicoll]

While reviewing #28064, I was wondering if "Let's" should be expanded to "Let us". I wasn't sure so I didn't apply that.

[Buzzardo]

"Let's" should always be expanded. It is a contraction of "Let us".

[HiuKwok]

I did a global search on codebase, and I only see one occurance of deny, and I don't think that makes sense to swap it with prevent, hence we can probably mark We should when possible change "deny" to "prevent". as done.

[wilkinsona]

Thanks, @HiuKwok. I've done that.