0

As we know, English exists in many dialects.

In another life, over 20 years ago, I spent a year and a half in Japan, teaching English. I was under no obligation to teach standard American English but I had no desire to mark my students exclusively on their grasp of standard British English, either.

So I did my best, whenever a discrepancy between the two emerged (in spelling or in common communicative phrases) to give my students both forms and recommend that they use whichever they were most comfortable with, but that they should endeavour to use either standard American or standard British on a consistent basis.

Two decades later and I find myself writing technical documentation for web-technologies.

It seems to me that the web has its own dialect, Web English, which generally resembles American English but isn't (because it will be used as readily by Australian or British English speakers as by US English speakers).

Hence we have:

  • color
  • background-color
  • text-align: center

But if we regard this as Web English (and I recognise that some will insist that it's not that - it's simply American English), should documentation also be written using Web English, to maintain consistency?

Normally I write using British English terminology and British English spelling. But, to maintain consistency, is it recommended that I write technical documentation in the same Web English as my HTML / CSS / Javascript?

E.g.

  • you can define the element's color with the CSS property color
  • you can define the element's background color with the CSS property background-color
  • you can center the text by giving the CSS property text-align a value of center

Tangential question:

If I do all that, what am I supposed to do with "parentheses"? Just use American English?

13
  • 2
    I am reminded of how we are all stuck with an HTTP header named referer because Phillip Hallam-Baker didn't know how to spell "referrer"... – stangdon Apr 7 at 20:25
  • 2
    I don't think technical terminology constitutes a "dialect". I wouldn't even call it English if I were to pick nits. That would be similar to saying "try-except-finally" structures in technical documentation should follow English grammar instead of the syntax of the programming language the documentation is about. The only reason it's background-color instead of background-colour is because that's what the specification of the language says it should be. – ColleenV Apr 7 at 20:30
  • 3
    The property names are jargon and only incidentally english. In some other language, the property would still be center but the surrounding text would not. As an AmE speaker, I would think nothing was amiss when reading "use center to centre text." – Yorik Apr 7 at 20:32
  • 2
    @Rounin Absolutely. The spelling in the English text should be consistently BrE or AmE throughout, but computer language elements should be used as they are specified. – ColleenV Apr 7 at 20:34
  • 1
    A more subtle example comes from AmE punctuation normally being placed inside what in technical documentation would be a string literal. Probably relates to parens handling. – Yorik Apr 7 at 20:35
3

If there is such a thing as “Web English”, it’s definitely not what you are describing.

The entities in a computer language are not English. They may look like English words to make it easier for people to remember them, but they are syntactically distinct.

The background-color entity is no different than declspec or __init__. The only valid spelling of those identifiers is the spelling defined in the specification of the computer language. There’s no such thing as “Python English” even though the Python language has quite a few elements that look like English words.

Often, a book will list the typographical conventions it will use to help the reader distinguish code from English text. The preface of Programming C# 8.0 is a good example.

Because ‘code’ is not English even though some parts of it might look like English words, it’s perfectly acceptable to use whichever spelling you prefer in the English text. “You can define the element's background colour with the CSS property background-color.” is correct if the rest of the text is using British spelling.

0

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.