[Mesa-dev] docs: consistent language

[Erik Faye-Lund]

Just one detail to fill in:

I just got a question on #dri-devel if this suggestion would place an
additional burden on most developers to additionally look up every word
of new documentation to see if it's US or UK English.

I'm not proposing to place any additional burden on people writing
docs. I think it's fine if people do a best-effort (which arguably can
be low; this isn't a very important detail), and then we'll either
catch things during reviews or fix it up afterwards.

It's not like the Mesa docs are perfect in terms of spelling or grammar
anyway, I just want to resolve which of the forks in the road we follow
trying to clean things up ;)

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?
> 
> The MR in question:
> https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/8572
> 
> Ian's response:
> https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/8572#note_808593
> 
> Previous changes:
> https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/6864
> https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/6894
> 
> 
> _______________________________________________
> mesa-dev mailing list
> mesa-dev at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/mesa-dev