Nesdev wiki talk:Manual of Style/RFC 2119

This should be deprecated or deleted

After Bregalad left a comment about the use of MUST, I ended up taking a look at the use of this template across the wiki.

This should not be part of our manual of style for this wiki (do we even have one? this seems to be the only page in this namespace). All of these words have perfectly normal English meanings, and those are the meanings that new users come in expecting. Putting them in ALLCAPS and insisting that they have some specific meaning (which is only obscurely different from their normal English meaning) creates confusion and slows comprehension of the article. An infobox wasting 100 words to try to explain that "MUST" means "must, but pedantically" is counter-productive. The capitalization style of RFC 2119 is jargon used only by a few particular groups of people; the vast majority of users are not familiar with it, and it wastes our time.

I looked through the wiki and found no use of this template that I thought contributed to better understanding of the meaning of the words in question, and I found several cases where MUST was being used incorrectly. I'd recommend deleting this page, though this wiki doesn't seem to have a deletion request process. - Rainwarrior (talk) 11:49, 26 May 2015 (MDT)

Why in hell does typing RFC 2119 automatically create an external link??? - Rainwarrior (talk) 11:51, 26 May 2015 (MDT)

Mediawiki feature(?): http://www.mediawiki.org/wiki/Manual:RFC —Lidnariq (talk) 13:15, 26 May 2015 (MDT)

See RfcKeywords on W3C Wiki. If MUST was being misused, it should be fixed. But just because something can be misused doesn't mean it's useless. For example, look at all the other RFCs that cite this RFC in the same way the {{RFC 2119}} template does; is it useless there? And if it's useless, why is the delusion that it's useful so widespread? Should I reword all uses of all-caps MUST along the lines "Failure to do so causes undefined behavior"? --Tepples (talk) 16:55, 26 May 2015 (MDT)

No, absolutely DO NOT redefine what "MUST" is supposed to mean and try to impose this new personal definition of the word on others. That's my primary issue with this! You're creating nonstandard meanings for words and then expecting others to read some documentation to keep up with you. The word "must" is perfectly fine already; just use English words as they already exist. I don't care if some people have a use for RFC 2119 elsewhere, it's not helping here. - Rainwarrior (talk) 17:30, 26 May 2015 (MDT)

"personal definition"--The IETF is hardly a person creating a personal definition; RFC 2119 is a standard set by the organisation eighteen years ago. (As for tepples creating a "personal definition" he is just suggesting a rephrasing this particular meaning of MUST into the vernacular; not redefining it.) "perfectly normal"? English (well, language in general) is fairly extensively ambiguous. I think it is[/was] useful for distinguishing these particular meanings. The group that uses these...is those creating technical computer document specifications, which we are/do; I find it useful to discriminate advice for complying with the specification from requirements of the specification. Furthermore, not all of our readers are native English speakers. Defining the difference between should and must is a useful thing. (And one doesn't have to click if one doesn't find it necessary to be clarified, meaning no time lost!)(Perhaps better to contend a wide adoption to counter "particular groups of people", than its usefulness? Using it to imply usefulness is an argumentum ad populum.)Myask (talk) 17:43, 26 May 2015 (MDT)

Perhaps more saliently, "If you don't carefully and clearly define the words you use in communications, you will fail to communicate. Standards documents are – first and foremost – about clear communication of an agreement on how to do a thing." http://www.quora.com/Whats-the-story-behind-RFC-2119 Myask (talk) 17:47, 26 May 2015 (MDT)

Sorry, I misread what tepples said. (I thought he was suggesting editing the template to define MUST = otherwise undefined behaviour, which would have been even worse.) I'm saying that we should not encumber our text with unnecessary definitions. I don't disagree with RFC 2119 as a practice on how to personally use these words, but I absolutely disagree with an annoying and intrusive infobox to explain them everywhere they appear, and with UNNECESSARY capitalizations of PARTICULAR words for NO REASON other than they're relevant to some ESSAY you once read about how to USE them. If you think the word "must" is used ambiguosly in an article fix the text to resolve the ambiguity, don't slap ugly formatting an an infobox and a link to some 5000 word essay about how to use these words on it! We don't need to offer definitions for every use of a word, we should present the words clearly so they can be understood in context. - Rainwarrior (talk) 18:02, 26 May 2015 (MDT)

The capitalization is intended to distinguish the RFC 2119 readings from the far less precise dictionary readings. --Tepples (talk) 18:35, 26 May 2015 (MDT)

I wouldn't mind at all if you included this template on talk pages, if you wanted to use it as part of a comment suggest to an editor how it may be helpful to use these words (if some editor were consistently misusing them), but I am very strongly opposed to suggesting to the reader how they are supposed to read them by placing it within articles. When editing you should acknowledge the naive reading of your words, and accomodate that by using them well, not by telling the reader to get with the program and read this essay first. - Rainwarrior (talk) 18:15, 26 May 2015 (MDT)

"The naive reading" of the word bit is "a small portion", not "an individual switch that can be set to a low or high value". --Tepples (talk) 18:35, 26 May 2015 (MDT)

Just, please do not propose an infobox explaining the word "BIT", capitalizing it wherever it is used with a link to a 10 page essay about what it means. - Rainwarrior (talk) 18:51, 26 May 2015 (MDT)

For what it's worth, I'm in agreement with Rainwarrior on this matter. I've no issue with RFC2119 or its purpose, but adding an infobox (or anything else similar in concept) to pages to add nothing more than clarification of what English words mean is, quite literally, excessively pedantic. As someone who has (obviously) written technical documentation for decades, know that pedantry of this sort ends up making the documentation more confusing to readers. (For sake of comparison, the same goes for excessive linking). The purpose of a piece of technical documentation (re: NES/Famicom) is not to reassert dictionary definitions, it's to convey technical details. Leave the job of a dictionary to a dictionary; if there are thoughts/details which are unclear or vague given their wording, simply fix the wording (or provide multiple phrasing, e.g. what I did with the Attribute Table description in nestech.txt). TL;DR: I think what's going on here is ridiculously excessive OCD and catering to it does not help make documentation any clearer. - Koitsu (talk) 18:34, 26 May 2015 (MDT)

Rainwarrior wrote in this edit summary: (and then saying it's a "specification"?) But what is this wiki if not the specification of the Nintendo Entertainment System virtual machine as understood by homebrew developers and emulator developers? --Tepples (talk) 18:35, 26 May 2015 (MDT)

Please stop treating everything I say as some black and white absolute. I think the choice of words was poor on those two edits. It's not wrong to say it's a specification, but I think it was terrible form to say it that way. - Rainwarrior (talk) 18:38, 26 May 2015 (MDT)

There is three reasons to ever use words in all caps:

1) If lowercase is not available. This is clearly not the case in this wiki 2) For acronyms. 3) To indicate that you are shouting loud.

Here the capitalization of MUST looks like an accronym but in context its clear its not, instead it is shouting. I believe that shouting like that and saying THIS MUST NOT BE DONE! NEVER! FORBIDDEN! do not suit a technical documentation style and should be forbidden (no joke) on this wiki. Do not assume the reader is a 3 years old kid who can't think for himself, you don't have to say "Do NOT cross the road!" like you'd shout a small kid (for his own safety), instead, say "if you're going to cross the road, be aware that there is also vehicles on it, and many drivers tends not to respect speed limitations.". Any adult person knowns exactly what this means.

In short, I agree with Rainwarrior. I do not even know what RFC2119 is and I do not care. This is not related to NES development in any way. Bregalad (talk) 03:28, 27 May 2015 (MDT)

I do not agree. RFC 2119 is good in many cases. (However, that doesn't mean it should be used everywhere.) --Zzo38 (talk) 14:55, 28 May 2015 (MDT)

Are you disagreeing with the idea that we shouldn't stick this template all over the articles and capitalize MUST and SHOULD, or are you just stating your approval of RFC-2119's definitions of must and should? (I have no problem with it as a suggested guideline for editors on how to use the words; it's the template and capitalization that I object to.) - Rainwarrior (talk) 15:43, 28 May 2015 (MDT)