(everything phrased in debate format simply for clarity, not because I'm resolute)

There are plenty of style guides to choose from just like there are plenty of standards to choose from. Oh the pleasure of debating CMS vs. Strunk & White...

If a common noun, or combination of words, is used in a manner specific to Waze, it should have emphasis (capitals, italics, color, underline, whatever the style standard dictates). This ensures that the reader understands that there is more nuance than the words present on the page indicate and does so in a concise way.

I do believe most technical style guides also agree with this, though I'm struggling to find a common way to reference it. Many use formatting other than capitalization -- such as bold or italics -- so as to not run afoul of "proper noun" standards or risk offending the "readability." Ditch CMS and S&W, we've got the Microsoft Writing Style Guide!

Having to add clarifying context instead of using a mark-up element is the antithesis of clarity. It only reduces the likelihood that the reader gets it wrong, instead of easily and explicitly calling out the text that is more than the sum of its parts.

Examples of things I consider Waze-specific that might not qualify under proper noun styles but would earn emphasis under my recommendation (in whatever chosen formatting element):

1. Junction Box - far more than the sum of the words, it's a particular Waze construct, with back-end processes, rank restrictions, editing practices, etc.
2. Private Road - means something different than "private road" as you're not talking about the real-world traffic restrictions necessarily, you're talking about how the segment attribute is going to influence routing.
3. Area Place - You bet this has Waze-specific meaning. Ask any new L1 who did it "wrong." It is a whole set of attributes and best practices, not simply a map representation. We've got tables, and carefully refined guiding text... why would we not essentially hyperlink this every time it is used?
4. Major Highway - even to a seasoned editor, sometimes you mean the Waze segment property, sometimes you don't.
5. Map Problem - You're not referring to something in the abstract. It's a specific thing in Waze, detected by a process, complete with a WME layer. Sure, it's also a problem with the map, but that's not how we're using it most of the time. Though sometimes, yeah, we're saying "that's not a user error, that's a map problem." (and we're not meaning an MP to be worked and closed out)
6. Update Request

Things which do not have Waze-specific nuance (the words carry no hidden additional meaning), and thus should not receive emphasis:

1. node
2. segment
3. place
4. road
5. speed limit - doesn't matter that it's a segment attribute, it's not being used specially in Waze
6. regional coordinator - a Waze RC is not a nuanced use of "regional coordination"
7. turn arrow

I concur that almost all English style guides, including ones focused on technical documentation, do not capitalize jargon or terms of art. That doesn't mean those styles guides are necessarily the best for our wiki.

Most of the phrases and nouns under consideration are accurately classified as terms of art. "gigabyte" is an easy jargon word to use clearly in technical documentation, as it has no other non-technical meaning. "Minor Highway" on the other hand has a "precise, specialized meaning" for Waze editors: It's shorthand for "road segment(s) with the Road Type parameter set to 'Minor Highway'." The full form is a bit of a mouthful to repeatedly use, hence the term of art naturally arose.

The challenge as I see it is that terms of art, when not identified as such by formatting or capitalization, are exclusionary. They cater to the ingroup and can be frustrating to an outsider attempting to learn.

If we don't call out our specialized uses, the reader only has experience and context at their disposal to differentiate "minor highway" (a road not considered especially important) from "minor highway" (a road segment with the Road Type parameter set to 'Minor Highway'). If they're a brand-new editor, they might not be aware that "Minor Highway" is a parameter and will definitely read a lowercase use of minor highway incorrectly!

As the primary goal of our Wiki is to provide clear and concise instructions to both new editors and veterans, I struggle with not calling out our terms of art visually, simply because that's how style guides intended for broad arrays of topics instruct. Those guides also often instruct to avoid jargon whenever possible, and to call out the first use of jargon if unavoidable.

A definitive example is "map problem."

a recent posting in Discord wrote:The New York UR project could use your help.
...
Seeking 5 newer editors to be trained to use all available clues, tailored and friendly questions to improve the probability of getting answers from UR reporters, and to working together with the waze community to solve map problems.

Are we solving map problems... or are we solving Map Problems?

Or, we could just go the German route and capitalize 100% of nouns

Don't go look at the capitalization in the WME layers menu...

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

1. 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.
   1. This is analogous to using the spelled-out version of an acronym on first introduction.
   2. 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.
   3. Subsequent acronym usage has the automatic visual distinction of multiple capital letters. Terms of art do not.
2. 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.
3. 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.
4. 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.

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:

colored text as a placeholder for templated style wrote:See this additional page for more details on how to map parking lots.

Use the Parking Lot Road type for all necessary segments in the parking lot.

This type:

• should be used inside Apartment Complexes, Schools, and Universities unless it meets the criteria for Private Road found in the next section below.
• has a penalty when transitioning to another segment type. This should prevent Waze from routing you through a parking lot or an alley as a shortcut.
• can be used to avoid "missing road" automated Map Problem reports.
• can be used to prevent Waze from assuming drivers driving slowly or parked in the parking lot are in a traffic jam on the main road. Draw in the drivable portions of the parking lot that are near outside roadways.
• prevents Waze from highlighting segments with slow speeds (automatically detected traffic jams)

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

colored text as a placeholder for templated style wrote:

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

DwarfLord wrote: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.

I think this is an example of where re-using the colored lozenge may be the most clear and concise approach. On terms of art that are hard conflicts in a confusing manner with existing non-Waze language, that'd be my leaning in approach. When we're using phrases with more intrinsic Waze uniqueness such as "junction box", once that term has been introduced in that wiki section, it's safe to re-use it without any additional formatting.

If one where to write an authoring rule around this, it'd probably have to be a list of Waze terms that collide with existing words or phrases in a potentially-confusing manner. "DO use markup whenever using these words and phrases in a Waze-unique manner: freeway, local street, ..."

Under this method, only a segment (entrance/exit/highway) that actually traverses a collection point, such as a tollbooth, recording gantry, transponder reader or ticket dispenser, is marked as toll. This means that all paths use a single toll segment per collection point, and they are only assessed with a single penalty, whether "avoid toll roads" is on or off.

The natural way to represent a phrase where a literal marking is specified is to quote it: 'marked as "toll",' much the same way one would say 'mark it with a "T".' The element in WME is a checkbox named "Toll road", so at a minimum it should say 'marked as "Toll road."'

A potential rewrite could be "...or ticket dispenser is configured with toll parameters" to avoid making any literal WME element references, either directly or indirectly with an adjacent word/phrase.

100% agree

DwarfLord wrote: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?

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

Capitalizing noun phrases adds clarity when such phrases are commonly abbreviated by use of acronyms. Example: Residential Point Place (RPP). I’m not sure that The Chicago Manual of Style would agree, but it makes sense in the context of how we use such phrases in our Wazeopedia.