Usage issue: question words in headings

(Janet Swisher) #1

The recent history of the Live Samples article illustrates a pattern that I’ve seen any number of times on MDN:

  1. Native-English-speaking writer (e.g., Sheppy) creates a heading of the form [Question-word] [noun phrase] [verb phrase] (“How the live sample system works”).
  2. Possibly-not-native-English-speaking contributor (e.g., ajith913) sees the question word, thinks this heading is a question, and adds a question mark to the end of it (“How the live sample system works?”).
  3. Native-English-speaking contributor (e.g., sideshowbarker) sees the question mark, realizes that the heading is not a well-formed question in English syntax, and adds the “helping verb” does to the heading, making it a syntactically correct question (“How does the live sample system work?”).

I posit that this pattern arises because the form [Question-word] [noun phrase] [verb phrase] is easy for non-native-English-speakers to mis-parse, if they have not internalized all the use cases for when adding do is necessary, or prohibited, in English. In many languages other than English, [Question-word] [noun phrase] [verb phrase] is a valid syntax for a question. In English, it is a short hand for This section describes [question-word] [noun phrase] [verb phrase]. In English, the corresponding question syntax is [Question-word] [do|does|did] [noun phrase] [rest of verb phrase]?.

I propose that we adopt a style guideline:

If a heading starts with a question-word (who, what, where, when, why or how), make sure that it is in the form of a question, and ends with a question mark.

This imposes a slight burden on native-English-speaking writers to avoid an otherwise valid structure, in the interest of easing the cognitive burden on (potentially millions of) non-native-readers.


(Eric Shepherd) #2

So… this is an interesting point, and a good one to bring up. I agree this is something we should adjust in our English writing, but I think we should go the other direction:

Don’t start headings, page titles, or page slugs with a question word (who, what, where, when, why, or how), and don’t write headings in the form of a question. This provides consistency and makes the text easier to translate effectively.

Instead of “How to dismantle a thermonuclear snoozle” or “How do I dismantle a thermonuclear snoozle?”, write “Dismantling a thermonuclear snoozle”.

I think the more action-oriented form “Dismantling a thermonuclear snoozle” is just more compelling anyway. Plus question marks in titles and headings just invites bugs to crop up.


(Janet Swisher) #3

How to [verb phrase] [noun phrase] is a slightly different structure, though more common. We have a whole section of the /MDN/Contribute tree for How-to articles. I hadn’t thought about those when I made my proposal. We could rename them all, though it would be tedious.

I’m having trouble coming up with a descriptive non-question rephrasing for “How the live sample system works” other than something snooze-inducing like “Structure and operation of the live sample system”. No doubt that’s a lack of creativity on my part.

(Chris Mills) #4

This sounds like a reasonable guideline to me.

For “How the live sample system works”, you could just rephrase that one as a question — “How does the live sample system work?”

(Eric Shepherd) #5

Unless you’re trying to avoid questions (which I think we should). Then I’d go with something like “Inner workings of the live sample system” or “Live sample system internals” if it’s a truly technical guide or “Working with the live sample system” otherwise.