7 ms·

I'm currently trying to get some folks on the same page regarding the most basic of things in a design document, and the passive resistance is just astonishing

I'm currently trying to get some folks on the same page regarding the most basic of things in a design document, and the passive resistance is just astonishing to me. Just adding the following text seems to upset some people: The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. It's like they don't want to be pinned down to an exact meaning in design documents! And don't even think about trying to "force" people to use a style guide like RFC 7322, or even an authoritative list of initialisms, acronyms, and abbreviations. Is it too much to ask to have people use the same term to refer to a project, environment, component, etc? It saves so much time when you don't have to spend effort tracking down what someone means when they say "stage is broken". This has already gotten too rant-y but it burns my butt so much! So much wasted effort!

rhapsodic 7y ago
> Is it too much to ask to have people use the same term to refer to a project, environment, component, etc? It saves so much time when you don't have to spend effort tracking down what someone means when they say "stage is broken". I disagree with you, but since I'm shadowbanned, there's no point in explaining why.
chrisseaton 7y ago
I don’t think the key to effective writing is following a bunch of standards.
- MivLives 7y ago
  Standards like grammer?
  - fizwhiz 7y ago
    Not sure if your typo was intentional.
  - jknoepfler 7y ago
    That's a pretty asinine response to a point that is substantially correct. Insisting upon a set of rules for otherwise commonly understood words (an RFC defining "MUST") is usually a pedantic waste of time, and will actually reduce the quality of the finished product. No one is here to dispute the usefulness of approximately correct contemporary grammar. I would dispute the usefulness of insisting that design docs conform to APA style requirements or some other nonsense, unless there were very clear reasons for insisting on that level of uniformity (documentation for a pacemaker, for example).
    - walshemj 7y ago
      You are assuming that everyone working with the document is a native English speaker and / or has worked to a standards based development system. Even so back in the day ICL managed to ignore a counter MUST start from Zero in implementing an X.400 stack - and you wonder why the uk No longer has a mainframe supplier.
      - chrisseaton 7y ago
        If people can't understand the simple word 'must' how will they understand the more complicated words that RFC 7322 uses to define it?
        colanderman 7y ago
        That's… not the point of RFC 2119. The point is to specify specific words used to indicate various levels of adherence to a standard. Maybe "must" clearly indicates a strong requirement to you (as opposed to an optional requirement). Does "should"? How about "shall"? The English interpretation of these words contains shades of grey, and different people will interpret them differently, sometimes even depending on context. Why invite such ambiguity? It leads to problems, when the designer writes "shall" and the implementer takes it as a suggestion, or the designer writes "should" and the implementer sinks months trying to satisfy what turns out to be a requirement the implementer intended as optional in light of unknowns. Clarifying terms eases communication. RFC 2119 isn't about defining basic words of the English language for imbeciles. It's about selecting words to indicate precise levels of compliance. They could have equally named the levels P0, P1, and P2. Instead they chose MUST, SHOULD, and MAY to indicate the same, while reading more easily as part of a sentence.
- technofiend 7y ago
  >I don’t think the key to effective writing is following a bunch of standards. Well it is if you're being judged on compliance to the standard. Have you never worked in government? But hey if you don't like the standard then just make your own: the great thing about standards is there are so many to choose from!
  - mannykannot 7y ago
    That is how you get compliant language; whether it is effective language depends on what it says.
  - briandear 7y ago
    It depends on what you are writing. Also, there is a question of readability. A document written in legalese is certainly “accurate,” but that doesn’t make it comprehensible. Writing with clarity isn’t about following a standard, it’s about using language in such a way that the consumer of that language understands the message. If documents were written following like the RFC, they’d be incredibly tedious to read. English isn’t a computer language, there is a such thing as context, tone, and diction. Of course if you are actually writing a legal document or standards document, certainly use that idiom.
    - deleted 7y ago
      [deleted]
- sonnyblarney 7y ago
  It's the key to 'effective communication' in particular environments. Words have meaning, and because language is vague, we help it a little by pinning down the meaning of certain words: this is for clarity, it's not a constraint.
djakjxnanjak 7y ago
Maybe your colleagues perceive that they are being asked to study a bunch of off-topic material. Is reading RFC 2119 really the most productive use of their time?
- thrower123 7y ago
  If they can't be bothered to read and comprehend the two pages of RFC 2119, preferably in an hour or less, it raises grave doubts about their capacity to operate in a technical capacity. We kinda have to do a shitload of reading and understanding to know how things work - at least that is what I find myself doing most of my time.
- dabraham1248 7y ago
  https://tools.ietf.org/html/rfc2119 https://tools.ietf.org/html/rfc2119 is 664 words, including links, author's contact info, headers/footers, etc. Also it's basically "what that word means in English". I don't think it takes that long to study.
jschwartzi 7y ago
Without knowing why you want the RFC 2119 language adopted within your organization, I can say that although it's very important that everyone use the same words to refer to the same things, I would be careful when applying rigorous definitions to those keywords. Are you writing standards for networking, where there could be multiple implementers and you want to be clear to everyone what their implementation has to do? What value do the definitions add? Do people ask questions or have disagreements without the rigorous definitions?
iscrewyou 7y ago
Show them civil engineering codes, specs, and plans. It’s nothing but those words. You can pull up ASCE standards, the IBC OR CBC, Caltrans Highway Design Manual or Specs, Greenbook, Any city design manual, etc. etc. They’ll get the idea.
JoshTriplett 7y ago
When you say "must" with the weight of RFC 2119, you need to consider the "or what?". If you're writing a standard, what force does it carry? Is there a certification? Is it a marketing issue? Will other implementations put the bad implementation on a blocklist? Will they actually fail to interoperate in practice? Or can someone get away with violating the "must"?
- TeMPOraL 7y ago
  For in-house design documents: or you're not a team player. You've done a bad job. This will screw up something, somewhere, at some point, costing people time and money.
deathanatos 7y ago
You might like the additional followup standard, RFC 6919: https://tools.ietf.org/html/rfc6919 https://tools.ietf.org/html/rfc6919 > RFC 2119 defines a standard set of key words for describing requirements of a specification. Many IETF documents have found that these words cannot accurately capture the nuanced requirements of their specification. This document defines additional key words that can be used to address alternative requirements scenarios. Authors who follow these guidelines should incorporate this phrase near the beginning of their document: > The key words "MUST (BUT WE KNOW YOU WON'T)", "SHOULD CONSIDER", "REALLY SHOULD NOT", "OUGHT TO", "WOULD PROBABLY", "MAY WISH TO", "COULD", "POSSIBLE", and "MIGHT" in this document are to be interpreted as described in RFC 6919. (Spoiler: this is an April 1st RFC. That said, I have wanted to use or used "OUGHT TO" so many times…)
- StavrosK 7y ago
  What's the difference between "OUGHT TO" and "SHOULD"?
puzzledobserver 7y ago
Is it really wise for design documents to rely on nuances of language? How many of your readers could you reasonably assume have read RFC 2119? How many of your readers could you reasonably assume to be native English speakers? How many native English speakers would be able to comfortably articulate the difference between "shall" and "should"? And no, not every design document is intended for professionally-licensed engineers, safety-critical applications, or to be used in legal courts. Even when safety is not at stake, writing remains important. If you find yourself relying on technical and prescriptive descriptions of language use, isn't it perhaps a good idea to think about what exactly you're trying to convey?
munchbunny 7y ago
I think asking for RFC compliance is asking people to pay too high of an up front effort cost for what you are trying to achieve, unless you really are writing standards and not sketches of features. What is the problem you're actually trying to solve? People not implementing to spec? That's seldom solved by changes to language, and more often solved by an engineer getting asked to fix an incorrect implementation.

rhapsodic 7y ago

> Is it too much to ask to have people use the same term to refer to a project, environment, component, etc? It saves so much time when you don't have to spend effort tracking down what someone means when they say "stage is broken". I disagree with you, but since I'm shadowbanned, there's no point in explaining why.

chrisseaton 7y ago

I don’t think the key to effective writing is following a bunch of standards.

MivLives 7y ago
Standards like grammer?
- fizwhiz 7y ago
  Not sure if your typo was intentional.
- jknoepfler 7y ago
  That's a pretty asinine response to a point that is substantially correct. Insisting upon a set of rules for otherwise commonly understood words (an RFC defining "MUST") is usually a pedantic waste of time, and will actually reduce the quality of the finished product. No one is here to dispute the usefulness of approximately correct contemporary grammar. I would dispute the usefulness of insisting that design docs conform to APA style requirements or some other nonsense, unless there were very clear reasons for insisting on that level of uniformity (documentation for a pacemaker, for example).
  - walshemj 7y ago
    You are assuming that everyone working with the document is a native English speaker and / or has worked to a standards based development system. Even so back in the day ICL managed to ignore a counter MUST start from Zero in implementing an X.400 stack - and you wonder why the uk No longer has a mainframe supplier.
    - chrisseaton 7y ago
      If people can't understand the simple word 'must' how will they understand the more complicated words that RFC 7322 uses to define it?
      - colanderman 7y ago
        That's… not the point of RFC 2119. The point is to specify specific words used to indicate various levels of adherence to a standard. Maybe "must" clearly indicates a strong requirement to you (as opposed to an optional requirement). Does "should"? How about "shall"? The English interpretation of these words contains shades of grey, and different people will interpret them differently, sometimes even depending on context. Why invite such ambiguity? It leads to problems, when the designer writes "shall" and the implementer takes it as a suggestion, or the designer writes "should" and the implementer sinks months trying to satisfy what turns out to be a requirement the implementer intended as optional in light of unknowns. Clarifying terms eases communication. RFC 2119 isn't about defining basic words of the English language for imbeciles. It's about selecting words to indicate precise levels of compliance. They could have equally named the levels P0, P1, and P2. Instead they chose MUST, SHOULD, and MAY to indicate the same, while reading more easily as part of a sentence.
technofiend 7y ago
>I don’t think the key to effective writing is following a bunch of standards. Well it is if you're being judged on compliance to the standard. Have you never worked in government? But hey if you don't like the standard then just make your own: the great thing about standards is there are so many to choose from!
- mannykannot 7y ago
  That is how you get compliant language; whether it is effective language depends on what it says.
- briandear 7y ago
  It depends on what you are writing. Also, there is a question of readability. A document written in legalese is certainly “accurate,” but that doesn’t make it comprehensible. Writing with clarity isn’t about following a standard, it’s about using language in such a way that the consumer of that language understands the message. If documents were written following like the RFC, they’d be incredibly tedious to read. English isn’t a computer language, there is a such thing as context, tone, and diction. Of course if you are actually writing a legal document or standards document, certainly use that idiom.
  - deleted 7y ago
    [deleted]
sonnyblarney 7y ago
It's the key to 'effective communication' in particular environments. Words have meaning, and because language is vague, we help it a little by pinning down the meaning of certain words: this is for clarity, it's not a constraint.

djakjxnanjak 7y ago

Maybe your colleagues perceive that they are being asked to study a bunch of off-topic material. Is reading RFC 2119 really the most productive use of their time?

thrower123 7y ago
If they can't be bothered to read and comprehend the two pages of RFC 2119, preferably in an hour or less, it raises grave doubts about their capacity to operate in a technical capacity. We kinda have to do a shitload of reading and understanding to know how things work - at least that is what I find myself doing most of my time.
dabraham1248 7y ago
https://tools.ietf.org/html/rfc2119 https://tools.ietf.org/html/rfc2119 is 664 words, including links, author's contact info, headers/footers, etc. Also it's basically "what that word means in English". I don't think it takes that long to study.

jschwartzi 7y ago

Without knowing why you want the RFC 2119 language adopted within your organization, I can say that although it's very important that everyone use the same words to refer to the same things, I would be careful when applying rigorous definitions to those keywords. Are you writing standards for networking, where there could be multiple implementers and you want to be clear to everyone what their implementation has to do? What value do the definitions add? Do people ask questions or have disagreements without the rigorous definitions?

iscrewyou 7y ago

Show them civil engineering codes, specs, and plans. It’s nothing but those words. You can pull up ASCE standards, the IBC OR CBC, Caltrans Highway Design Manual or Specs, Greenbook, Any city design manual, etc. etc. They’ll get the idea.

JoshTriplett 7y ago

When you say "must" with the weight of RFC 2119, you need to consider the "or what?". If you're writing a standard, what force does it carry? Is there a certification? Is it a marketing issue? Will other implementations put the bad implementation on a blocklist? Will they actually fail to interoperate in practice? Or can someone get away with violating the "must"?

TeMPOraL 7y ago
For in-house design documents: or you're not a team player. You've done a bad job. This will screw up something, somewhere, at some point, costing people time and money.

deathanatos 7y ago

You might like the additional followup standard, RFC 6919: https://tools.ietf.org/html/rfc6919 https://tools.ietf.org/html/rfc6919 > RFC 2119 defines a standard set of key words for describing requirements of a specification. Many IETF documents have found that these words cannot accurately capture the nuanced requirements of their specification. This document defines additional key words that can be used to address alternative requirements scenarios. Authors who follow these guidelines should incorporate this phrase near the beginning of their document: > The key words "MUST (BUT WE KNOW YOU WON'T)", "SHOULD CONSIDER", "REALLY SHOULD NOT", "OUGHT TO", "WOULD PROBABLY", "MAY WISH TO", "COULD", "POSSIBLE", and "MIGHT" in this document are to be interpreted as described in RFC 6919. (Spoiler: this is an April 1st RFC. That said, I have wanted to use or used "OUGHT TO" so many times…)

StavrosK 7y ago
What's the difference between "OUGHT TO" and "SHOULD"?

puzzledobserver 7y ago

Is it really wise for design documents to rely on nuances of language? How many of your readers could you reasonably assume have read RFC 2119? How many of your readers could you reasonably assume to be native English speakers? How many native English speakers would be able to comfortably articulate the difference between "shall" and "should"? And no, not every design document is intended for professionally-licensed engineers, safety-critical applications, or to be used in legal courts. Even when safety is not at stake, writing remains important. If you find yourself relying on technical and prescriptive descriptions of language use, isn't it perhaps a good idea to think about what exactly you're trying to convey?

munchbunny 7y ago

I think asking for RFC compliance is asking people to pay too high of an up front effort cost for what you are trying to achieve, unless you really are writing standards and not sketches of features. What is the problem you're actually trying to solve? People not implementing to spec? That's seldom solved by changes to language, and more often solved by an engineer getting asked to fix an incorrect implementation.