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)
- 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)
- 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)
