Murky indeed!

After consideration of the various links posted, I still believe capitalization of certain Waze-specific noun phrases is justified, correct, and clearer to the reader (especially the naïve reader). BUT, I do NOT believe that any of the following reasons justify that capitalization:

• Terms of art — that phrase refers to jargon, e.g. "Once you've disconnected the Flux Capacitor from the Hyperdrive, refill the Quantum Synthesizer with Quadrotriticale". I agree we shouldn't capitalize just because something is jargon.
• Emphasis — perhaps the best-known exemplar of this approach is A. A. Milne: "...while he waited for Piglet not to answer, he jumped up and down to keep warm, and a hum came suddenly into his head, which seemed to him a Good Hum, such as is Hummed Hopefully to Others." Although I find this style Really Delightful in a children's book, I agree we shouldn't capitalize just for emphasis.
• Spelled-out form of acronyms — we're all familiar with phrases like "not in my back yard" (NIMBY). But we don't capitalize them when writing about them; we don't say that the latest WME release is Fouled Up Beyond All Recognition (unless we're playfully echoing A. A. Milne). I agree we shouldn't capitalize just because something corresponds to an acronym.

This being said, we're still dealing with terms that, as herrchin pointed out, have Waze-specific nuance. It is as if they are indicating a specific instance of an invisible common noun such as "tool", "type", or "object". I think this holds the answer.

For example, the sentence "Each segment that is added must minimally have the Country, State, City, and Street information" (Map Editing Quick-start Guide) capitalizes the names of the specific information types. This makes sense because the actual common noun is "information" and "Country, State, City, and Street" indicate a Waze-specific instance of that information.

We could write the same sentence leaving out the word "information" as: "Each segment that is added must minimally have a Country, State, City, and Street." This is still understandable in the context of Waze editing. But what if we then removed the capitalization from the "obvious" common nouns? We'd have "Each segment that is added must minimally have a country, state, city, and street." To me this is less clear.

So likewise, in a sentence such as "By default, Waze routes to an area place as if there were an entry point located at its center" is really saying "By default, Waze routes to a Waze object of type area place as if there were a Waze object of type entry point located at its center". If we actually wrote that latter sentence, we'd have to capitalize Area Place and Entry Point because they are acting as specific modifiers for "Waze object".

So that's my sense of it. Just because we are omitting nouns like "tool", "type", "field", "object", etc. modified by the specifying noun adjunct, they are still implicit, and the specifying noun adjunct remains capitalized even though it's not as obviously an adjunct any more.

...he said, Humming Hopefully to Others...

EDIT — Let's say a hotel has multiple conference rooms available for conventions and the like, but has given them names that happen to be common nouns: the City Room, the Highway Room, the Junction Room. Now let's say the author of a convention guide wants to be more concise, and so writes "Delegate badges may be obtained in the City. The keynote is at 9AM in the Junction, and the break with coffee and tea is at 10:30 in the Highway". Just because the word "room" has been omitted does not make this capitalization wrong.

Kartografer wrote:In other fields, there is no need to capitalize specific types of other things. In physics no one capitalizes up, charm, strange or top as the types of quarks, for example, even though each of these words means something very different elsewhere.

The critical difference between physics and Waze is that we use a lower-case 'p' for physics and an upper-case 'W' for Waze.

In other words, physics itself is a common noun, so the parts of physics that are not named after people are also common nouns. But Waze is the proprietary product of a private company. That affects how we treat nouns created by and unique to that company. If we capitalize Waze, that means things that are specific to Waze are also capitalized.

Going back to the hotel example. Let's say we are writing a general guide to ALL hotels. If we happen to mention conference rooms specific to one individual hotel, for example the Forest Room and the Mountain Room, we capitalize because we're talking about a unique room. But when we write about the luggage room, the laundry room, or the exercise room, we don't capitalize because ALL hotels — "hotels" with a lower-case 'h' — have such rooms.

Let's say Holiday Inn management decides that ALL Holiday Inn hotels will have conference rooms named the Highway Room and the Junction Room. Now those names are no longer unique; every Holiday Inn has one, just like every Holiday Inn has a luggage room. But would we not still capitalize them? Yes, because the Highway Room and Junction Room are specific to Holiday Inns.

Even if Marriott and Hilton joined in the practice and started having a Highway Room and a Junction Room in their hotels too, we would still capitalize, because the naming is not an implicit feature of all hotels, it is a deliberate choice on the part of specific hotel chains.

To look at this a completely different way, let's say I am playing Scrabble with a cherished family member of yours who knows nothing of Waze. We have agreed to make one modification to the rules in order to allow common noun phrases as well as single-word common nouns, but the rule prohibiting proper nouns (and of course proper noun phrases) still holds. Would you back me up if I beat your family member by playing "areaplace"?

sketch wrote:Your examples do not track with the situation at hand and I think the reasons why are pretty obvious.

I disagree.

For the sake of completeness and best forum practice: I've come to believe that the specific question of whether certain Waze noun phrases are common or proper is, for all practical purposes, undetermined. In the absence of consistent guidance from Waze management, I now see both perspectives as potentially correct, or at least very difficult to refute. I would like to drop the discussion of common vs. proper noun phrases. Hat-tip to Kartografer for engaging with me on this topic, both in this thread and in private discussions, with care, respect, positivity, openness and thoughtfulness. I really appreciate it.

But regardless of the proper/common question, the concern remains that certain nouns and noun phrases have special meaning within the context of Waze. If we agree that terms referring to detailed functionality specific and unique to Waze should be highlighted somehow, what is the best way to highlight them? Capitalization is surely the fastest and easiest way to do so, and it is convenient in multiple settings (forum, Discord, and chat, as well as in formal guidance).

I don't regard as persuasive the idea that we should abide strictly by rules developed for encyclopedias when we are writing an instruction manual for a specific proprietary product and have been granted extraordinary flexibility to make it as clear, succinct, and informative as possible.

I do, however, sympathize with the concern that capitalization may strike some readers as distracting. This is really a matter of taste, and in my experience it is virtually impossible to forge consensus around taste. Personally, I believe that the other methods of highlighting are no less distracting, and meanwhile those other methods are harder to apply in contexts other than formal guidance.

To me the tradeoffs strongly favor capitalization.

Aside: All this would be so much easier if Waze personnel were consistent. Out of curiosity, I looked up the forum post in which a Waze employee (Ohad-Ron) first introduced the new "Places" feature to the volunteer community:

viewtopic.php?f=8&t=86708

Even in that introductory post directly from Waze, the capitalization of "Places" was inconsistent!

voludu2 wrote:I suggest we NOT regard technical terms like "minor highway" as proper nouns.

Yes, if you read my post immediately before yours you'll see I have stood down from that idea. In our current circumstances I believe the question of proper/common is undetermined and I suggest we spend no further time discussing it.

voludu2 wrote:What we are really trying to do when we capitalize these terms is to emphasize them.

I respectfully disagree. We are not trying to emphasize them, the way A.A. Milne used capitalization to emphasize a Very Small Heart that can nevertheless hold a rather large amount of Gratitude. If all we wanted to accomplish was emphasis, I would not favor capitalization, because we are not writing a children's book. Rather, we are trying to differentiate the terms.

We find ourselves in an uncommon situation that is not supported by encyclopedia style guides. Specifically: the technical terms we use to identify highly detailed, Waze-unique functionality happen to be exactly the same as common English nouns that have nothing to do with Waze.

For example, here is a sentence from Ohad-Ron's official announcement of the Places feature:

ohad-ron wrote:Overlapping places - in a few places there are duplicate or very similar Places on of top of another. It is safe to delete one of them.

If you read the whole post, you'll see Ohad-Ron did not try too hard for consistency. But even he felt it was important to distinguish, in the context of the quoted sentence, the difference between a place and a Place. I feel likewise. Otherwise I fear we invite confusion, especially on the part of novices.

We seem to be converging on clarity about the usefulness, particularly to novices, of distinguishing terms used with Waze-specific meaning from the identical terms used as Waze-independent common nouns. How best to accomplish that distinguishing is a different but important question.

Capitalization is, as herrchin notes above, the "least common denominator", being by far the easiest to implement in all mediums. My concern about color highlighting and other more complex approaches is that they may be more distracting than capitalization. If reader distraction is a concern, then I would think capitalization would win on that count as well?

Nevertheless I am very glad for the discussion. I'm wide open to being persuaded that other approaches are better than capitalization. Change my mind!

p.s. In the passage herrchin quotes above is a reference to "Apartment Complexes, Schools, and Universities". I wonder what the person who originally capitalized that intended? Schools and Universities are official Waze categories, but apartment complexes are not...Anyway, the fact it threw me illustrates the power of capitalization as a hint or cue that what looks at first like an ordinary English word may have some additional meaning in the context of Waze.

Kartografer wrote:So I guess I'm just not seeing the rationale, need or benefit of capitalizing for distinction in our wiki.

Would it be accurate to summarize your perspective as follows:

• There is little chance that novice readers will be confused if we do not highlight to distinguish common English nouns and noun phrases used to convey Waze-specific meaning from those used for their dictionary meaning;
• If a wiki author is concerned about such confusion, that author should write or rewrite the text to clarify via context even if potentially sacrificing brevity and concision; and
• Since the above mean that clarity can be reasonably assured without any kind of highlighting (except possibly once per term, at its first use in an article), there is no compelling reason not to adhere to external style guides that advocate minimal highlighting.

Is that a correct summary?

P.S. I have been shown an instruction manual that used capitalization to distinguish every usage of key words that could otherwise be confused with common English nouns. So there is indeed precedent for this approach. But I don't want us to throw external style guides at each other because that merely begs the question. I want us to determine how to make our writing as clear and concise for novices as possible.

Thanks, this helps. We agree with a lot that is on that list. But...

• Another part of writing clearly is avoiding ambiguity and unnecessary repetition of these terms. I'm not sure about sacrificing brevity; oftentimes this goes hand-in-hand with brevity

What does "avoid ambiguity and unnecessary repetition" mean when our technical terms are exactly the same as common English nouns? Must we avoid the common English noun as well the technical term?

For example, if we find a concise way to talk about routing via local streets, must we rephrase it to avoid the term "local street" for fear the reader may confuse it with "local street"? Or, can we assume the reader will know that when we say "place" we just mean "place" and not "place"?

Asking authors to avoid technical terms where the writing would favor them, for fear of "unnecessary repetition", risks stilted language. Asking authors to avoid not only the technical term but its identical common English noun doubles that risk.

• If we write like this, clarity can be reasonably assured for everyone without any additional highlighting, and there is little chance that novice readers will be confused.

Yes, but at the cost of rewriting to avoid both the technical terms and their identical common English nouns (except where strong context makes it clear). Is this not a high price to pay?

• Highlighting should be used sparingly, or else it can overload the reader and become meaningless, just as incorrect capitalization has.

Agreed, highlighting becomes a net negative when overused. However, capitalization is much easier on the eye than other forms of highlighting.

And, "incorrect capitalization"? Are we starting with the unquestioned premise that, to be "correct", capitalization must follow an external style guide? Well, I question that premise.

We are writing an instruction manual for a single proprietary product, not an encyclopedia or a textbook or a novel for general consumption. For us, capitalization in the service of clarity is no vice! Let us not prejudge it as "incorrect" simply because it violates external guides that do not apply to us. Let us instead make it serve our purposes of clarity and concision.

Kartografer wrote:

DwarfLord wrote:Is this not a high price to pay?

I don't think it is. I've been looking around the US wiki to try to find things that would need to be rewritten. Could you give me an example?

Sure, the road types article will need substantial overhaul.

First, of course, the source code for all the colored lozenges (Freeway, Major Highway, Minor Highway, etc.) will have to be redone so they use lower case instead of capitalization. Thus freeway, major highway, minor highway, and so on.

Then, a thorough review will be necessary to remove those colored lozenges altogether everywhere they're used, except for the first use in each section, and replace them with lower case run into the text. This is the removal of distracting highlighting which we've been discussing.

Once that's done, we will find ourselves with text like the following, which was excerpted from the section on major highways. (Note, I have extended the example to use lower case and remove highlighting for jargon/technical terms from other sources as well as from Waze; since that appears to be the proposed principle, I must imagine that it is intended to be consistent.)

The following roads are to be classified, at minimum, as major highway :

• Roads classified in FHWA's functional classification as principal arterials or other principal arterials.
• Roads classified in FHWA's functional classifications as other freeways and expressways which do not meet the criteria for freeway.
  • This includes partially-limited-access roadways (or "expressways"). These are roads that have a lot of the characteristics of freeways, but also have occasional at-grade intersections with other roads.
  • Note: Every partially-limited-access roadway is a major highway; this does not mean that every major highway must be partially-limited-access.
  • Note: "expressway" is used as a shorthand term for partially-limited-access roads. This does not mean every road named "expressway" is a major highway.
  • Note: Some states refer to this class as other freeways. In these states, every road in this class is a freeway.

Perhaps it's just me? But I perceive this example as noticeably less clear than its current published form using capitalization. Seems to me that the lower-case conversion would require substantial analysis and rewriting for clarity.

For example, "other freeways and expressways which do not meet the criteria for freeway." I fear a novice might have a hard time parsing that now that all the highlighting is gone.

dfortney wrote:the technical specifications use a style convention of capitalizing defined terms; specifically, the first letter of each word of a defined term is capitalized.

So far in this thread we have discussed various reasons for highlighting Waze-specific terms, some more persuasive than others. It's been offered that we might want to highlight because such terms:

• Are terms of art (i.e. technical jargon);
• Ought to appear stronger (i.e. should be emphasized);
• Are sometimes abbreviated with capital letters (e.g. PR for Private Road);
• May be closer to proper nouns than common nouns; or
• Need to be distinguished from their identical common-English counterparts.

Now, thanks to dfortney's post, we can add

• Defined terms — terms that have "specific defined meaning within the standard".

I think this nomenclature hits the nail on the head. Highlighting defined terms helps the reader avoid "relying on the plain English meaning which may differ or lead to ambiguity".

Now the companion question is: if we choose to highlight defined terms, what form of highlighting is best and when should we use it? The comments have come up several times that highlighting is distracting, therefore we should write in such a way as to minimize use of defined terms, and/or highlight them only some of the time. I want to respond to each of these comments.

Highlighting is distracting. In principle I agree. Highlighting through capitalization, however, is significantly less distracting than colored lozenges or other markup techniques. It is also readily accessible in all forms of text communication.

We should minimize use of defined terms when we write. I vehemently disagree. Authors should be free to write the clearest, most concise guidance they can, even if that means using a defined term multiple times in a paragraph. A sentence that has been contorted to avoid defined terms for fear of distracting highlighting may end up being more distracting and harder to parse than a simpler sentence with them. It may also take more time and effort to write. Give the author the freedom to chose what's best.

We should highlight defined terms only some of the time, for example only when they are first used in a section. I disagree. A primary purpose of highlighting a defined term is to avoid the ambiguity relative to the common English words. Highlighting defined terms only some of the time defeats that purpose and would appear inconsistent.

To me, the arguments continue strongly to favor a policy of (1) highlighting defined terms whenever they occur and (2) doing so using capitalization.