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.)
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.
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, …”
This is a great example. Thanks DL! TBH the wording here has bothered me since I started wiki editing years ago. We could do what Blaine says and make an exception list. That would not look bad. Or we could write it like this:
Notice that the “criteria of a controlled-access highway” is how it’s worded in the freeway section on this page, so wording would be more consistent. Ironically, the capitalization in the original version (Some states refer to this class as Other Freeways. In these states, every road in this class is a Freeway) combined capitalization of Waze terms and FC terms, and the ambiguity is still there. At least for me; I remember doing a double-take as a L1 editor when first reading this.
I know this is a double post, but I got to thinking about this subject again as I worked on my proposednew toll page today, which is based on PesachZ’s toll roads page from four years ago. I found myself wondering about statements like
Here we are using the word toll (just one word in this case!) to refer both to real-life roads where you drive on them and pay money, and to an attribute of a Waze road segment that has special effects on routing behavior. Are these unclear? I thought about highlighting or capitalizing the Waze meaning of toll. Here’s how it would look capitalized:
Then I wondered if there was a way to avoid unnecessary ambiguity at least in the same sentence. I came up with this
This gives consistency. Seems clearer to me at least. So anyway, I thought the toll page was an interesting example of a word used simultaneously in real-life context and Waze context on the same place, and how context and word choice can influence the clarity. I’d love suggestions on how to better write it
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.
Thanks. I like the “toll road parameters” idea. Since we were talking about just the toll road attribute and not the toll free restriction, I decided to change a few sentences to say that. So the sentence from above now reads
I was attending a meeting of an international standards body last week, and I noticed that the technical specifications use a style convention of capitalizing defined terms; specifically, the first letter of each word of a defined term is capitalized.
The standards body, EMVCo does not have a published style guide. I asked the head of technology about it, and he confirmed that the style is deliberately done, as it is believed that readers of the standards are benefited by knowing that a term has a specific defined meaning within the standard vs. relying on the plain English meaning which may differ or lead to ambiguity.
For example, in the standard on Secure Remote Commerce, some of the defined terms could easily be confused with common nouns. (E.g., Cardholder, Digital Card, Dynamic Data, Payment Token). I personally find the capitalization convention quite helpful, even though a majority of the time it’s clear from the context alone whether a defined term is being used.
I’m in support of adopting this capitalization practice for the US Wiki, as it would make apparent when defined terms are being used, coaxing the reader to interpret the sentence accordingly, and providing a nudge to go look up any term with which the reader is unfamiliar. Particularly for novice and intermediate editors who are zooming into a specific section of the wiki, it would be helpful to know that certain terms have specific meanings, and sometimes those specific meanings do not align with the English definitions (e.g., Private Road).
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.