[Mesa-dev] docs: consistent language

[Erik Faye-Lund]

On Mon, 2021-03-15 at 13:44 +0100, Erik Faye-Lund wrote:
> TLDR; I'm proposing to standardize on US English in our public-facing
> documentation.
> 
> I proposed an MR a while back that changed the only occurrence of the
> UK English spelling "optimisation" for the US English spelling
> "optimization", which is already used 34 times in the docs. I've done
> similar changes in the past.
> 
> But this time Ian brought up the good point that picking a preferred
> language should probably be done using group consensus on the mailing
> list than just picking what's currently most popular.
> 
> So, I hereby propose to pick US English as our default language for
> user-facing documentation.
> 
> I'm not proposing to force anyone to use a particular English variant
> for things like comments, commit messages or variable names. I don't
> think there's much value in enforcing that, and I think it'd be
> perfectly fine if any particular driver wanted to pick a particular
> variant of English.
> 
> The main reason I want to standardize on an English variant is that
> I'm
> trying create a word-list for domain-specific/technical language to
> detect spelling mistakes in the docs more easily. And not having to
> add
> both US and UK English words makes this list easier to maintain. I'm
> not planning on going 100% systematically though the dictionary to
> detect UK English words that might be in my system dictionary, just
> to
> fix the words that currently cause me (a tiny amount of) pain ;)
> 
> The main reason why I'm proposing US English over for instance UK
> English is that this seems to be the dominant variant currently in
> the
> documentation. So it seems like the pragmatic choice to me.
> 
> Thoughts? Any objections to sticking to US English in the docs?

OK, so almost two weeks has passed, and I've only gotten a single
objection to the proposal, but a handfull of variations of voices in
favor of the proposal.

I suspect this is as close to a consensus we're going to reach. Since
it's not 100% consensus, I think maybe the best option is to take
Kenneth Grauke's suggestion of making this a recommendation rather than
a rule.

So my plan is to write up a patch for the docs that explains that we
recommend writing docs in US English. That should IMO make it clear
that we don't require people to spell-check to make sure that they're
using the "right" variation of English. At the same time, it's clear
enough that we're happy about patches moving towards US English.

It seems we're missing docs on how to write docs anyway (I guess that's
meta-docs?), so I guess this is a good time to add this.