We discussed this here 1-2 years ago, but we didn't seem to reach a strong consensus. The weak consensus, at least as I understood it, was to not to capitalize Waze objects but to capitalize some unique properties such as the road types. I practice this, and my position hasn't changed since then. In case I wasn't clear then, a few quick thoughts (will have more time to write later):

I don't think ambiguity is a big issue, and I don't think capitalization is the best way to solve it anyway. Rather, use context and synonyms to avoid the ambiguity. I haven't found anywhere in the wiki where capitalization of something has been a better solution than using context and synonyms. Furthermore, one doesn't just say something is a proper noun out of convenience; it either is or it isn't a proper noun. It seems that this question can go rather deeply into philosophy, but here's Wikipedia https://en.wikipedia.org/wiki/Proper_noun
Waze objects (segments, places, map comments, cities) are common nouns. Some attributes are proper nouns, like road types and place categories, because their names uniquely identify them. There aren't multiple private road types. There is one Private Road type.

Consistency is important. We don't have to follow Wikipedia style, but we should be consistent with how we write. Currently almost all of the wiki (besides the military base page) AFAIK has Waze objects in lower case but road types and categories in upper case. IMO this works well and is better than an alternative of capitalizing all Waze objects.

DwarfLord wrote:

Kartografer wrote:Waze objects (segments, places, map comments, cities) are common nouns. Some attributes are proper nouns, like road types and place categories, because their names uniquely identify them. There aren't multiple private road types. There is one Private Road type.

Can you explain in more detail why private road is specific but area place is general?.

Area places are a class of nouns. There are many, all over the map, rather than one single entity named Area Place. You can edit or PL specific instances of them. Private Road is a single entity (a road type) that is applied to various road segments, such as segments that represent driveways or private roads. It has unique properties, like a high transition penalty and a gold color in WME. It's the same with the category Hospital / Urgent Care (a specific entity). This is applied to various places that represent hospitals, urgent care locations, emergency rooms (classes of nouns). I'm in favor of capitalizing those terms that refer to a type or category. I am not in favor of capitalizing classes of objects like Area Places, Junction Boxes, Nodes, Segments or Cameras. This is actually how WME does it, at least in default English. Objects are not capitalized beyond what sentence case requires (it says "Junction box" in the drop-down); road types and place categories are.

It's also how we normally write. I don't see people in Discord writing about "Segments" or "Nodes" or "Cities" or even "Places" or "Junction Boxes", even those who expressed their support here for capitalizing these in the wiki. Nor do I see anyone else complaining about ambiguity in Discord due to lack of capitalization in what folks write there.

If we do decide to capitalize Waze objects, even if they are common nouns, where do we draw the line, and why? If we capitalize all Waze objects, I think readability would decrease a good bit. We would get things like:

Creating and editing Road Segments wrote:There are five essential steps to add Roads to the Waze map:

• Draw the Road.
• Set or confirm the Road properties.
• Connect the Road with Junctions to existing Segment(s) or another newly created Segment(s).
• Set allowed Turns at Junctions.
• Save the changes.

Now maybe if you come from a certain profession such as the military, where capitalization is used more widely due to tradition (which is why the Military Bases page has its own unique capitalization), this may appear normal to you, but all technical writing guides and even many new DoD writing guides recommend capitalization only of proper nouns. And this isn't the military anyway.

This is a community and a wiki about mapping, and mapping will always have some ambiguity between physical reality and abstract representations thereof. That's OK, because we want the map to represent physical reality. Also, as map editors, most of the time we are talking about the stuff on the map anyway, so this is the default understanding. Again, where disambiguation is needed, use context. So let's take your examples from the first post and try to add some context. Which is easiest to read and understand?

contrived wrote:"We should prefer junction boxes to box junctions."
"Although it's a major highway through the reserve, it should still be a private road."
"Was the driver's entry point at the hospital complex at the entry point or somewhere else?"

capitalized wrote:"We should prefer Junction Boxes to box junctions."
"Although it's a major highway through the reserve, it should still be a Private Road."
"Was the driver's entry point at the hospital complex at the Entry Point or somewhere else?"

contextualized wrote:"We should prefer junction boxes to control routing through complex intersections."
"Although it's considered a major highway through the reserve, we should still use the Private Road type for it."
"Did the driver's route end at the at the entry point for the hospital place or somewhere else?"

Or how about:
"Place the point place at the front door of the place" vs "Place the Point Place at the front door of the place" vs "Position the point place over the front door of the building" - Just be intentional about how you write.

One might argue that new editors or non-editors don't understand how terms like "entry point" or "area place" refer to abstract things on a screen rather than physical realities. That may be true, but capitalization doesn't help. One will still need to explain what these things mean, and that's what the wiki does. Also, when talking about Waze objects in URs to non-editors, one needs to use context, so the wiki should be a good example of that. Capitalization is of little use in clarifying what "the Road has a Closure on it" means to a reporter.

Tl;dr Waze objects (things that you can edit or PL) are common nouns, but some other functionalities in Waze (road types, place categories, the Waze Map Editor itself, Live Map) are proper nouns. We should continue to capitalize only proper nouns, like Wikipedia does, because:

1. Ambiguity is not a big problem in the wiki.
2. Capitalization doesn't really help to disambiguate.
3. Consistency is important in documentation.
4. If we decide to capitalize some Waze objects, we must capitalize them all everywhere or come up with a more complex standard.
5. This reduces readability due to distraction.
6. We do not write like this in everyday writing.
7. The wiki is not written like this currently.
8. Context and synonyms are adequate to disambiguate, where this is needed.
9. Context and synonyms are necessary anyway for new editors and UR reporters.
10. The wiki should be a good example of how to write about these things.

DwarfLord wrote:Kartografer, thanks very much for the carefully considered post. I recognize and appreciate the care and hard work involved.

I want to clarify that I consider this a discussion, not a proposal; thus the [DISCUSSION] flag in the title. My current goal is simply to understand the different perspectives better so I can make a more informed judgement.

I meant to say at first (before I started thinking about linguistics I guess), thanks for starting this discussion, and really thanks for restarting other discussions lately in this forum. Sometimes this process can be a little exhausting, but it's fun when we can build agreement together.

DwarfLord wrote:My initial sense is that, for the purpose of our wiki, these terms should be treated as proper noun phrases and capitalized because to do otherwise risks confusion.

herrchin wrote: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!

mhh60 wrote: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

The main reason you gave for capitalizing Waze technical phrases was not that they are proper nouns, but in order to reduce confusion we should treat them like proper nouns. I read that, perhaps incorrectly, as "pretend they are proper nouns and capitalize them as such." Blaine and Mark seem to have spoken from that understanding as well: Even if some Waze technical phrases are common nouns, there is benefit to capitalizing them or otherwise marking them up.

DwarfLord wrote:Further, I would never argue that common nouns or noun phrases should be capitalized. I doubt anybody here would. We can surely stipulate full consensus on that.

It doesn't look like we have full consensus on that. This is the joy of discussion!

So let's talk about proper nouns, and then we can talk about markup.

Wikipedia on proper nouns wrote:A proper noun is a noun directly associated with an entity and primarily used to refer to that entity, such as London, Jupiter, Sharon, or Microsoft, as distinguished from a common noun, which is a noun directly associated with a class of entities (city, planet, person, corporation) and primarily used to refer to instances of a specific class (a city, another planet, these persons, our corporation)... The detailed definition of the term is problematic and to an extent governed by convention... In English, proper names in their primary application cannot normally be modified by an article or other determiner (such as any or another), although some may be taken to include the article the, as in the Netherlands, the Roaring Forties, or the Rolling Stones.

So basically, as I understand it, if people normally can use at least an indefinite article or determiner with a noun phrase, this noun phrase is by convention a common noun. Since English doesn't have some governing linguistic academy, we let convention tell us what to do. We don't say "a Waze Map Editor" or "any Ottonomy." Those proper nouns refer to single entities. It sounds archaic to say "these United States of America" because the United States of America has since become a single entity in the way we talk about our country, and thus it is a proper noun. So back to the road types. In the thread I linked above, I first said that road types should not be capitalized at all, but then shifted at the end. Regardless of whether the road types should be capitalized for disambiguation (as supported by Kent, Alan and sketch in that thread) they can be proper nouns if used as such. If we say, "Passageway has a vehicle-type-specific penalty" or "for roads through apartment complexes, use Parking Lot Road", we're referring to Passageway and Parking Lot Road as single entities (and this is what the road templates were intended for). If we say, "draw parking lot roads through corner gas stations", we're referring to parking lot roads as a class of individual segments. "There's a parking lot road mapped through the Shell station, and a parking lot road on the opposite corner through the BP station, and a junction box may be needed to improve turn data at this intersection" contains many common nouns but two proper adjectives, "Shell" and "BP," that modify the common noun "station." A similar use for road types as proper adjectives might be, "draw Freeway stubs [i.e. stubs of type Freeway] at certain wayfinders." The convention, at least to me in the wiki, is usually to write about road types as single entities. For example, from the road types page, we have sentences like this: "The following roads are to be classified, at minimum, as Minor Highway." The lack of an article indicates that this is a proper noun.

If we talked about Area Place as a single entity, like we do with the road types, then we could say that this is a proper noun too. As I look through the history of the places page, it seems that we actually used to do this in the wiki, but the writing evolved as places became more commonplace (har), from March 2014 to April 2014 to January 2015. By the time I started editing in late 2015, people said things like "draw an area place here" and did not say things like "use a Place of type Area here." The convention had changed to using this phrase as a common noun, and it has remained so.

As for markup, I like the Microsoft Style Guide that Blaine linked above. Here's what Microsoft says in regard to capitalization:

Microsoft Style Guide wrote:

• Use sentence-style capitalization most of the time. That means:
• Capitalize the first word of a sentence, heading, title, UI label (such as the name of a button or check box), or standalone phrase.
• Capitalize proper nouns. To learn more about proper nouns, see Nouns and pronouns.
• Use lowercase for everything else.
• Always capitalize the first word of a new sentence. Rewrite sentences that start with a word that's always lowercase.
• Don't use all uppercase for emphasis. (It's OK to use italic sparingly for emphasis.)
• Don't use all lowercase as a design choice. Although all uppercase is used occasionally as a design element, don't use it in text.
• Don't use internal capitalization (such as AutoScale or e-Book) unless it's part of a brand name.
• Don't capitalize the spelled-out form of an acronym unless it's a proper noun.
• When words are joined by a slash, capitalize the word after the slash if the word before the slash is capitalized.

It mentions using italics sparingly for emphasis. I fully support this, and we probably do need to add more italics in the wiki, at least when defining our terms. When talking about road types, the road templates serve a similar function. Blaine, you also mentioned hyperlinking. Yes! The first occurrence of a technical term in any section of a page should always get a link, if it is not defined in the section. We shouldn't link every subsequent occurrence of the term; that's just redundant, but yes, people need to know that these terms have very specific and possibly hidden meanings.

tonestertm wrote: In my previous research, I did end up unearthing a section of the Wikipedia Manual of Style (note: their capitalization, even in the title) which would seem to support capitalization for our situation, but I'd have to dig it up again, and that might take too long for me to get this posted while it's still current.

Finally, there is precedent for changing long-standing, if somewhat gossamer, "guidelines", even in the absence of a change in editing policy. There is no reason not to bring an indeterminate former discussion to life once again. Thanks to you, Dwarflord, for bringing this back to life.

I would love to see your section of the Wikipedia Manual of Style that supports capitalizing terms of art. What I see there says the opposite. Specifically MOS:SIGNIFCAPS says:

Do not use for emphasis wrote:Initial capitals or all capitals should not be used for emphasis...
This includes over-capitalization for signification, i.e. to try to impress upon the reader the importance or specialness of something in a particular context. Introduction of a term of art may be wikilinked and, optionally, given in non-emphasis italics on first occurrence.
Example: use The community of researchers in a field may produce a scientific consensus, not ... may produce a Scientific Consensus.

So why can't we just do that?

p.s. Many, many, many other style guides online say or imply this, that existence as jargon by itself is a not a reason to capitalize anything. There is also universal agreement that components of an acronym should not be capitalized merely to show how they comprise it. The Wazeopedia (proper name of the Waze wiki) is really just a user guide; let's write it as people write user guides.

How to capitalize things that aren't proper nouns is clear, but what constitutes a proper noun gets murky. That's where all these style guides rely on convention by pointing people to dictionaries. I had been arguing that the road types and place categories are treated as proper nouns, not because of capitalization but because we refer to them as single entities ("the following shall be classified as Minor Highway" not "the following shall be classified as minor highways). It's on the edge though and not fully consistent. I can go either way on whether these are proper nouns, but honestly I lean toward the view that they are not. We never refer to area place, junction box, etc as single entities, so it's clear that they are not proper nouns.

I'd be cool with not capitalizing road types outside of specific UI interactions like "select Minor Highway from the drop-down menu" - all standards support that, and relying on the road type templates and italics alone for markup, which are in wide use. I have been thinking about making a place category template too, to reflect how those appear in WME. I could draft stuff if anyone wants to see... Or we could keep it the same...

DwarfLord wrote:Although I find this style Really Delightful in a children's book

Me too! Great example

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

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.

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

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.

herrchin wrote:Are we solving map problems... or are we solving Map Problems?

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

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'?"

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?

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

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.

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

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.

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.

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

DwarfLord wrote: 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 at the beginning of 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 for attempting to summarize. That's close, but more restrictive on highlighting that what I've been trying to say. Let me revise:

Karto's position on markup in wiki wrote:

• We should always write clearly, no matter what, especially in the lead section of a page.
• Part of writing clearly is explaining and/or linking (which is itself a highlight) Waze-specific terms when they are first mentioned.
• 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 (notice Blaine's example about PLRs above).
• 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.
• If a term is reintroduced in a later section, an additional highlight or tooltip (whatever we decide on) may be used where it is first reintroduced.
• Highlighting should be used sparingly, or else it can overload the reader and become meaningless, just as incorrect capitalization has.
• External style guides, especially Wikipedia, basically advocate this (apart from proscribing extra highlighting due to accessibility concerns that don't apply to us).
• Therefore, the Wikipedia Manual of Style should continue to be used as our style guide, with the addition of an optional extra highlight per section.

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

1. Clarity
2. Readability
3. Brevity
4. Distinction
5. Consistency

p.s. You're right about how throwing manuals = begging the question, but I am curious about what your manual is