Aspnetcore.docs: Our "little" contraction problem

[guardrex]

Refactor topics to use contractions.

[rachelappel]

Contractions often don't localize well and non native English speakers often have a problem with them.

[guardrex]

I'm very confused. The style manual calls for them, and the rule has been enforced on every new and updated topic for over a year, including when I was working for @mairaw. No reviewer has ever stopped me or even hinted that I shouldn't be using them.

However if that's what we'll do, no biggie! My 😵 mad script 😵 just needs a tiny adjustment. We can kill that PR, and I can whip us up one to reverse their use across the repo.

@Rick-Anderson 🎖 ... your orders Sir?

[Rick-Anderson]

@nokura are contractions a problem for loc?
@scottaddie can you comment?

[scottaddie]

I prefer contractions, since that's what the style guide says to use. Here's the official guidance:

Write using the same, everyday words you use in conversation.

• Use common contractions, such as it’s, you’re, that's, and don’t, to create a friendly, informal tone.
• Don't mix contractions and their spelled-out equivalents in UI text. For example, don’t use can’t and cannot in the same UI.
• Never form a contraction from a noun and a verb, such as Microsoft’s developing a lot of new cloud services.
• Avoid ambiguous contractions, such as there’d, it’ll, and they’ll.

@nokura Has your team approved of this ☝️ guidance for localization?

[Rick-Anderson]

@tdykstra can you comment on contractions?

[tdykstra]

Scott is correct, current Voice guidance is to use contractions because it sounds more informal. There used to be a policy against them for localization/international English reasons, but that was quite a few years ago.

[mairaw]

Contraction is one of the top 10 rules for Microsoft style and voice. So, I'd imagine they considered Loc to come up with that. Internal reference link: https://worldready.cloudapp.net/Styleguide/Read?id=2700

[guardrex]

kk ... thanks everyone for TAL at this. I'd be totally cool either way, but I think we agree that consistency is a good goal.

@Rick-Anderson @scottaddie The current PR only covers the aspnetcore doc set. Would you like me to setup a 2nd PR that does the aspnet doc set? I suggest a 2nd PR because the :eye: strain on review will be rough if I merely add a commit to the current PR.

[Rick-Anderson]

Another PR, but very low pri.

[guardrex]

Of course, I understand. It takes like 15 seconds to run the script. It's all good ... right up until the eyes glaze over looking at the diff on the PR! Ouch. 😅