What English to use?

[psteinb]

We came to a small discussion on what kind of flavor of English language to use in Carpentry material, https://github.com/hpc-carpentry/hpc-shell/pull/4#issuecomment-416965288 People say that en_US is the default for Carpentry material. Can anyone confirm or point me to related documentation? We would love to stay consistent with the carpentries as much as possible.

Thanks, Peter

[fmichonneau]

@weaverbel please chime in!

[weaverbel]

Hi @psteinb We prefer to use UK English as our default - so ... travelling, not traveling; colour, not color; centre, not center; organise, not organize.

We are developing a style guide where this will be spelled out in more detail.

[psteinb]

@weaverbel thanks for providing this piece of evidence. I personally don't care too much, but we love for HPCCarpentry to stay consistent.

[pdoehle]

Should we be using the British convention for punctuation as well then? Periods and commas inside versus outside quotation marks, usage of single and double quotation marks for quotes within quotes, etc.

[rgaiacs]

We prefer to use UK English as our default

So why

$ grep -r organize _episodes
_episodes/02-filedir.md:It organizes our data into files,
_episodes/02-filedir.md:let's have a look at how the file system as a whole is organized.  For the
_episodes/02-filedir.md:your files are organized in a hierarchical file system.
_episodes/02-filedir.md:Nelle is ready to organize the files that the protein assay machine will create.
_episodes/05-loop.md:> Suppose we want to set up up a directory structure to organize
_episodes/03-create.md:> organized:

for the Shell lesson?

@weaverbel I'm reopen this one.

[maxim-belkin]

We prefer to use UK English as our default

Hmm, a couple of questions:

1. Who are "we"? Library Carpentry? The Carpentries?
2. Where is this decision documented? I don't see en_UK, UK English, or British mentioned in instructor-training, lesson-example, and styles repositories, nor on the websites for The Carpentries, Software Carpentry, Data Carpentry, and Library Carpentry.

[tracykteal]

'We' is The Carpentries. We chose it because it's more universally used, although we've been applying it to the overall website and documentation, and not necessarily uniformly on lessons so far. As @weaverbel mentioned, we have a draft style guide https://docs.google.com/document/d/10KutjajR-5RJfPAF8UQlxzcd8tx4PNFXH0acDFD2dBs/edit, but we want to shorten it to make it more accessible, and you're right it hasn't made it anywhere public facing yet. I created an issue to add it to the handbook around Communications. https://github.com/carpentries/handbook/issues/258

Most of the lessons in SWC, DC and LC use US English, but there's some UK English in them too. I'd like to get feedback from the different lesson programs (SWC, DC, LC) on what we want to use. So, I don't have an answer yet, but yes standardizing and communicating that standardization is important, so I'll work on this and get an answer.

[tkphd]

Thanks for the clarification, @tracykteal .It makes sense to unify the Carpentries headers and boilerplate using en_GB.

For the lessons, I wonder if there's a clever software solution that would "translate" based on the workshop organizer's locale or _config.yml key? It would be elegant and inclusive to ease up on hard-coding the dialect selection.

[maxim-belkin]

I like the careful wording of that document! 👍

It would be great to add guidelines on proper use of emphasis (the closest entry is "italics") and boldface.

Is this allowed?

e.g. or e.g.?

[maxim-belkin]

And, by the way, my reading of that document is: "there are no strict rules about which version of English to use when developing a lesson".

[tracykteal]

Yes, that's correct. There are not strict rules about which version of English to use when developing a lesson. General guidelines are that the language should aim to be clear and not contain idioms that are specific to a particular language or region. As we put together a style guide, we may provide more guidelines, but for now and going forward aiming for clarity and broad comprehension is a good general framework.

[tracykteal]

To @tkphd point, there are some ideas around being able to have the template component swap out and be the appropriate one based on language. https://carpentries.topicbox.com/groups/discuss/Tdb042c4bc0ecf365

The full text of the lesson would be more challenging, but doing something with the template elements seems possible and is something that would be great to do. The lesson infrastructure committee is working on several general updates. More ideas or help on that committee would be great too! https://carpentries.org/blog/2018/07/curriculum-vision/