When writing documentation for web-technologies that use American spelling, should the text also use American spelling?

Question

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?

Answer 1

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.