Dear technical copyeditors,
We need to talk.
I'm a technical author. I write books about programming. I don't speak or write proper English. Not my area of expertise. I need your help. But, please, don't overdo it. Here are some Do's and Don'ts that will make our life together easier.
He continues to present his philosophy of grammar and style. But I think the real value of Stoyan Stefanov's Poor English Skills(TM) is the following meta-message that is important for language learners everywhere :
You don't have to be perfect in English to be successful among English speakers, perform public talks, and write books in English. You just need to focus on enjoying being good at who you are and what you do.
So with the preamble and The English Learner's "Motivation For The Day" out of the way, let's critique Stefanov's now infamously questionable-yet-ideologically-defendable-by-him phrase:
Some strings that have a special meaning, as listed in the following table:
String Meaning Example
\ This is the escape character >>> var s = 'I don't know';
\n End of line >>> var s = '\n1\n2\n3\n';
etc. etc. etc.
The main problem with Stefanov's phrase is that it's long and it's not a sentence; we expect long phrases to be sentences. We have two primary options: make it shorter or make it a sentence. Let's take a look at various attempts to improve it:
"Some strings that have a special meaning, as listed in the following table:"
This is the original clunky clause containing a questionable comma. It reads too much like a sentence and you want it to have a full predicate like, "Some strings that have a special meaning are useful due to their magical powers, as listed in the following table:". But it's not there and you just read to the colon and feel like you must have missed something.
"Some strings that have a special meaning listed in the following table:"
This is OP's suggestion which creates a slightly-shorter noun-phrase. But it eliminates the
comma + as which helps to break the sentence into two parts Each part has a separate function; the part after
comma + as alerts the reader about the relationship of the first part to the stuff that follows the colon. Also, the word 'listed' initially sounds like the verb that all readers are desperately expecting; it doesn't serve that role and thus creates confusion.
Long, continuous noun-phrases can be hard to follow! Try the next noun-phrase just for fun. "My aunt's friends that had been at the party the night after she kissed the guy she met on a date with her girlfriend's best friend listed in the following table:"
"Strings that have a special meaning:"
This edit stays true to Stefanov's reductionist style which allows the reader to grok it for what it is: a describing noun-phrase, not a sentence. This has the implied subject-predicate, "The following are...". This option would be ok.
"Some strings that have a special meaning are listed in the following table:"
Adding a simple verb makes this an easy-to-read sentence! The phrase 'are listed' is now a true verb. It's an easier-to-read sentence because the expected elements are there.
"Some strings have a special meaning, as listed in the following table:" Again, this is a full sentence. The
comma + as listed is an idiomatic indicator of a transition in the sentence. When we see this form, we then know that this type of transition is taking place, relating the prior sentence (independent clause) in some way to the following material. It can be interpreted as "Some strings have a special meaning. And those special meanings are listed in the following table:"
The key to readability is providing the reader with expected elements in the right place. It can be OK to drop some elements when a sentence is short. But as phrases and clauses get longer, the need becomes greater for commas and
as's (and other such words, phrases, and punctuation) that break up sentence structures and mark sentence transitions -- all of which help the reader to read what they're reading.