[DISCUSSION] Wiki editing: capitalizing Waze noun phrases

Map Editors Community United States US Wiki Discussion
21

Me too! Great example :slight_smile:

I’m not sure I follow that we have to capitalize nouns that act as specific modifiers of other nouns. I don’t see this rule demonstrated anywhere else in technical writing; sometimes people may use quotes in object of type “x” phrases, or nothing. Proper adjectives can be derived from proper nouns and then substantivized (removing the noun they modify), like “Americans,” but that’s only because “America” was already a proper noun. 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. Instead they explain that these are the six flavors of quarks and what that means, if writing to a non-technical audience.

In the same way, regarding the filling in of address fields on segments, I think this is where we need to heed the WP instruction to avoid jargon and consciously write one level down, or in our case, down to level 1. So we could write that sentence like “Each segment must have the country, state, city and street name details filled into its address information after it is created.” If you write like this, and you should, again to provide a good example for (as Tony mentioned) how to talk with new editors and non-editors, extra capitalization adds nothing. One could also capitalize these words as they are in the interface by calling out the UI interactions, like “After creating a segment, you must click the field that says “No address” and fill in the fields labeled COUNTRY, STATE, CITY AND STREET; the None boxes may be checked as appropriate next to CITY and STREET.” This would also be stylistically correct (according to WP MoS), but the capitalization doesn’t make this any more understandable.
By the way, the conference room names in your postscript are proper names bestowed on the rooms by the owner, similar to the Blue Room of the White House. It’s just a name, and it may not even be very blue right now. Proper names can be shortened (like 30 Rock). I don’t think this applies to what we’re talking about.

I fully agree, and I don’t think anyone is arguing that we should not call out our terms of art visually. Although I may have implied that in my first few posts, I was assuming the use of links and text formatting (bold or italics), and I’ve come to see through this discussion that we need to add more of this formatting. The crux of the disagreement is whether we need capitalization to sufficiently call out our Waze terms of art.

Haha, I have been thinking about German, and that Discord thing threw me off as well. When I read it, my first thought was “Why couldn’t they just have said ‘to solve problems with the map’?” :lol:

Edit: Also, Marc made a good point about TLA hell. I’m guilty of it too in my writing. Why say “MTE” when we can just say “event”? And especially, why say “RTC” when we can just say “closure”?? I know it’s common to say that, but do we really need so many abbreviations? From what I can see, the abbreviations have been the hardest things for new editors to pick up on, and we should try to avoid them where we can. I was in a discussion about adding some information on upgrading road type continuity, and the discussion got lost over how to name and abbreviate this concept. Crazy! And very inaccessible to anyone new. Extra capitalization contributes to overuse of abbreviations.

If we mainly disagree over whether extra capitalization by itself makes our wiki easier to understand for newer editors, I have been wondering whether we should just ask a bunch of new editors. I have started to prepare some example texts… Still not sure where to draw the line though in what to capitalize in the More Capitalized Versions. Anyone want to propose a rule?

22

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”?

23

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

24

I disagree.

25

I think I see what you’re saying. Brands, products, services, apps and trademarks specific to a company are capitalized, but that’s not what we’re talking about. These terms we’re discussing are just descriptive terms for pieces of data, and many of them were not even created by Waze staff. They’re not trademarks, or else they would be publicly known and used. They’re not even set in stone. Junction boxes are (were originally) called big junctions, dirt roads became off-road/not maintained, area places have also been referred to as landmarks and venues… These are just descriptive terms. I understand that some of them have been customarily capitalized, but that doesn’t change what they are.

Interestingly, even trademarks, if used improperly often enough, become genericized, and their owners eventually lose the legal right to protect them, which is why Nintendo introduced the term “game console” to avoid having kids talk about “nintendos” so much that the trademark became unenforceable. By contrast, escalator became generic due to its parent company’s improper use of the term. The word no longer referred to the brand but rather to a class of objects, and other providers of this class of objects could use it freely, as a common noun. This just goes to show that status as a proper noun is dependent on convention, not around capitalization but around how a word is used to refer to an object. All these Waze terms that we have been discussing are not proprietary and are used as common nouns.

So this probably would be an apt but confusing and unrealistic example of genericized trademarks, or more properly service marks, I guess. In a single hotel, the names would just be proper names of single locations. In multiple hotels it might be a coincidence, but still proper names referring in context to single rooms. If Holiday Inn decided to name these rooms with uniform names throughout the chain, that would become a distinctive feature of their brand used for marketing (have your meetings at the Holiday Inn, with our new, improved Highway Room℠ conference experience). If the other chains started copying these names, the names would lose their distinctiveness and eventually become common nouns to refer to a class of rooms with certain similar characteristics. This is what has happened in some places with Jeep and Jet Ski. People talk about “jeeps” and “jet skis” when referring to any small SUV and personal watercraft. Chrysler and Kawasaki have fought to influence public perception away from using these names in these ways, because it erodes their brand.

But that’s neither here nor there. The Waze terms being discussed are not proprietary brands, products or trademarks. That’s why I agreed with Marc, when he said that your examples don’t track with the situation at hand.

So back to practicalities: We said that the Wikipedia style, used by WP and most other wikis, is not to capitalize terms of art but instead to use wikilinks, italics and whatnot to mark up, where necessary. This is also followed by another, much larger mapping community, OpenStreetMap, which also uses terms of art and talks about data objects with special terminology. Some of these are also marked up with templates. They do not capitalize closed way, for example, which is how areas are defined there, but they mark it with italics in its definition. This style works for them, although they also have inconsistencies in their wiki and are working to clean it up. So if all the style guides say not to capitalize these terms, and even a mapping wiki like ours (with a lot more special terms) can follow it, why can’t we?

If there’s still an issue of insufficient visual distinction for our Waze terms, I added the category template for place categories, and I am thinking about (if possible) some sort of a tooltip template where a term could have dotted underlines, and a mouse-over gives a glossary pop-up. How would that serve? It would be similar to wiki linking but maybe a little easier to use.

26

Don’t go look at the capitalization in the WME layers menu… :wink:

Having recently been fully submerged in raid wikis – reading, adapting, authoring, butchering… – I can summarize my recent writing experience as thus:

  • The first time a term of art is used in a document, it’s nice to hyperlink it to the page explaining it, if not in the current page.

  • This is analogous to using the spelled-out version of an acronym on first introduction.

  • However, unlike print (physical and virtual media), our wiki content is often transcluded or copied other places, and thus “first usage” can easily be lost.

  • Subsequent acronym usage has the automatic visual distinction of multiple capital letters. Terms of art do not.

  • Capitalization is an easy and natural thing to default to. I suspect this is because most writing we do is not “for print”; it’s chat/email. That doesn’t make it right for our wiki. We should mark up more distinctly for the wiki.

  • Writing “one level down” is definitely something that can be done in many cases. I just intentionally practiced this, and was able to purge a decent chunk of jargon without bloating the text. It’s not a swiss army knife though; sometimes you really do need the explicit terms of art.

  • I love the idea of using wikimedia templates, like Kartografer’s example for Category. When I think of our most-heavily marked-up page, my mind goes to Road types.

  • Terms of art are clearly identified.

  • Colors or other style elements can be mirrors of actual WME UI elements.

  • To a veteran it may seem a little overkill, but that is erring in favor of the novice, and erring in the favor of absolute clarity over what’s “cleanest.”

  • If we want to get crazy, we can put the hyperlinks in the templates. I’m 75% of the way to thinking this is a good idea.

27

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: [i]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:

https://www.waze.com/forum/viewtopic.php?f=8&t=86708

Even in that introductory post directly from Waze, the capitalization of “Places” was inconsistent![/i]

28

Based on the current discussion, my opinion is that it would be easy to adopt the en.wikipedia.org manual of style for the USA wazeopedia. It it fairly well thought-out. It would be possible to make some small modifications to take into account that nearly every article in the wazeopedia is a technical article, and that most of the articles provide “how to” or guidance (something that does not belong in the wikipedia mainspace articles), but I think it would be easiest to deviate as little as possible simply because each deviation requires a long discussion. It would take a while to bring all of our pages into compliance with this guideline, but that’s no reason not to adopt a manual of style. That way, anyone trying to fix misspellings, correct comma splices and other grammar errors, would know which way to go with capitalizations and other stylistic options at the same time - once the style guidelines are agreed, we don’t need to discuss such details in the same discussion as how to accurately represent facts about the Waze-provided products or the generally-accepted guidance on how to map.

I suggest we NOT regard technical terms like “minor highway” as proper nouns.
What we are really trying to do when we capitalize these terms is to emphasize them. We don’t need to try to cast them as proper nouns in order to justify emphasizing technical terms.
Instead of capitalizing for emphasis (this would be our only option on a platform with no formatting options), I suggest we follow the en.wikipedia.org style guidelines and wrap the emphasized text in <em>…</em> and/or start using the {{em}} wiki template to achieve the same. The USA wazeopedia produces italics when we use the <em> tags, based on the specifics of the “skin” (CSS style choices).

Wikipedia style guidelines say that the first time a technical term appears on a page (or if it is a long page, the first time it appears in a section), it should be wikilinked to a reference for that term. We could also use a tooltip for a hover-over-pop-up for the term, if the explanation is short enough to work in a tooltip, and if we have tooltips available. If a term needs to be emphasized at some other point in the text, use the <em></em> tag.

We can reduce the need for using emphasis, as well as the temptation to capitalize, by doing a good job defining our technical terms / jargon, and by writing pages as simply as possible. There is no need use “RTC” when writing about segment closures (except to note that some editors use that acronym as an abbreviation for closures). “FC” does not have an identical meaning to “road type” or even to “correct road type”.

29

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.

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:

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.

30

DwarfLord - I did read your posts, followed your discussion of reasons for and against treating technical terms as proper nouns, and I generally agree with you that we may be able to write more clearly and concisely about many topics if we have an easy and well-understood way to differentiate between technical and “everyday” use of some words that the editing community commonly uses. I had suggested doing this by using standard emphasis tags when introducing a term for the first time on the page, but I see that you are talking about something different.

This puts me in mind of how discussion documents and usage guides for various computer systems have long used special formatting/notation to make it easier to understand what is required, optional, etc, in a line of input. Some specialized documents even define their own grammar/notation. Wrapping things in various types of brackets is then well-understood throughout the document.

I don’t think a lot of square and angle brackets thrown in the middle of a block of text is going to make it easier to read, though. We might need some other type of formatting.
But I think I understand you saying you are looking for SOME KIND of way to consistently designate words being used as specific WME-related terms, rather than being used in their “everyday” sense.

Maybe that would work. Maybe by creating wiki template(s) like
{{place}} and {{freeway}}, or perhaps {{WME|place}} and {{WME|freeway}} and {{WME|<any word at all>}}.

There are a lot of options for what that {{WME}} wiki template would do to a word. Use a different font? Highlight, italicize, embolden, render in all caps, wrap in some kind of brackets, change the color? Whatever it takes.

If Ohad-Ron had had a nice {{WME}} template, and that template were set to create yellow highlights, he could have created:

We could also write

31

We already have a {{Freeway}} (of course capitalization can be changed if we get agreement on it), although some have said that this and the other road templates are distracting in paragraph text. But I agree with the idea and have already made a place category template along these lines. A template for WME words could be something like the WP HoverTitle tooltip template, which gives a dotted underline and a tooltip, or the OSM Tag template, which gives different font color, background and linking.

32

I strongly think we should limit the scope of our formatting intent to the wiki. While it would be nice to unify across all mediums, even the availability of italics is not always guaranteed. Capital letters are the lowest common denominator for sure, but enforcing that upon our wiki due to the restrictions of other platforms is not a great idea when we’re striving for wiki clarity.

If the templates are distracting in paragraph text, then my initial recommendation would be to rewrite the content to avoid repeating the templated term too much. For example, the Parking Lot Road section could easily be restructured without losing clarity:

33

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! :slight_smile:

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.

34

Totally agree. The color highlighting was extremely distracting and very difficult to read.

35

That’s why we should write to avoid unnecessary repetition and/or only use markup at the first mention of a term in a section. I’m pretty sure I’ve been saying both of these things since the first page, and Blaine and Renee said them just a few posts above.

Any markup for distinction should only be used where it’s necessary (again, of course, see WP MoS). Otherwise it loses distinctiveness. Even capitalization. But you can’t do that with capitalization without looking inconsistent and wrong anyway.

By the way, when I saw Apartment Complexes, I just thought it looked stilted and in need of fixing because of grammatical incorrectness. I didn’t even begin to think that it had some deeper Wazey meaning. I’m beginning to wonder if we simply have different paradigms about capitalization, and maybe it’s regional or something. I don’t know, but it feels like we’re going around in circles with this.

One other thing (probably said this before): What we’re writing is not that unique. Yes, it’s not a pure encyclopedia. Yes, it’s not a pure user guide. It’s a mixture of both. What else could it be? Definitely in the pages I write, I take an encyclopedic tone in some descriptive parts and a user guiding tone in the prescriptive parts. So why is there a need to break all the rules that have been accepted for both encyclopedias and user guides?

Nor is our jargon unique. I’ve attempted to show other examples, but really you just have to open up any user guide for any piece of software in existence to see common words that have been repurposed to describe something new within the system of the software, and these terms are never capitalized for the purpose of distinction. Did anyone capitalize window even in old MS user guides? No, you can check, they didn’t.

So I guess I’m just not seeing the rationale, need or benefit of capitalizing for distinction in our wiki. Sorry if I’m the broken record here.

Sent from my S9 using Tapatalk

36

:smiley: (I don’t have the ability to copy the current Road Type formatting into a forum post)

37

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.

38

Thanks for attempting to summarize. That’s close, but more restrictive on highlighting that what I’ve been trying to say. Let me revise:

If you want to further summarize, I’m saying that our priorities should be, in order:

  • Clarity* Readability* Brevity* Distinction* Consistency
    p.s. You’re right about how throwing manuals = begging the question, but I am curious about what your manual is :mrgreen:
39

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

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.

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?

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.

40

Sorry about the “incorrect capitalization.” I had intended to edit that to something that didn’t sound so rigid and absolutist. It would have been better to say “unconventional capitalization.”

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?

And the gets us back to the first page of the discussion. We started out looking at contrived prose, like “the junction box is the best way to box junctions.” But the JB page doesn’t have anything like that. The road types and routing server pages also have (IMO) nothing to rewrite regarding local streets, except for changing “street” to “local street” to reflect WME US English. They have sparing use of the road type template, which works well, and no repetition. The PLR part could use some rewriting, and Blaine gave an example of how to do it, which was essentially about replacing repetititons with pronouns. The most difficult part I can recall in avoiding ambiguity was when writing the guidance for multiple entry points. Instead of writing “place the entry point”, I ended up writing “position the entry point” but was probably not consistent. We could also probably cut down on repetition in the rest of the places page.

So I’m wondering whether it would be more helpful, instead of debating theoretical concerns, to discuss how best to write actual, specific texts from our wiki or proposed for our wiki. If that sounds good, feel free to criticize my writing. It’s all linked in my signature. I try to write my stuff according to the principles I have laid out here, but maybe it’s not concise or clear enough. Or we can talk about your work or anything else that’s in use or proposed.

Sent from my S9 using Tapatalk