Hacker News Reader

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

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.

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

That is how you get compliant language; whether it is effective language depends on what it says.

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.

Standards like grammer?

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

> Insisting upon a set of rules for otherwise commonly understood words (an RFC defining "MUST") is usually a pedantic waste of time

I would agree, except the field of programming seems to have a very large number of pedants. Unfortunately, earlier in my career I was in the room many times where the lead or programmers told the PM or stakeholder "well it didn't say that exactly."

>I would agree, except the field of programming seems to have a very large number of pedants.

It's been a few years but at least when I worked as a NASA subcontractor those standards were (IMHO) to both ensure compliance to process and frankly spread around the blame if something failed despite compliance. Since none of us are writing code to fly on the Space Shuttle I'll agree with you most of the time pedantry for the sake of it is a waste of time. Still, if someone wants to be a pedant about writing code for an automated teller machine or a voting machine then I'd say it's time well spent.

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.

I'm not a native English speaker. Half of the team I manage are native English speakers,the rest are not. The recent project they did on communication templates was checked by the French colleague,while I no longer forward some of the files to English native speakers because they can't form sentences thst are clear enough to understand by others. It is not easy for a lot of people.

I work with a team that spans native speaker to barely able to form English sentences, and communicating clearly in a mixed audience like that is really a completely separate skill from native language use.

For the ones with minimal English it's often clearer to use phrasing that a native speaker would say is obviously wrong, but matches their native language patterns. Or use simpler but not-quite-appropriate words.

And for the native speakers, the awareness (or self-regulation) to eliminate idioms and less common vocabulary is nigh-impossible for some people.

I find that awareness and avoidance of idioms is much easier once one has learned (well) a second language. I am fluent in Esperanto, and somewhat subconsciously translate much of what I write as I am writing it. It leads me to choose simpler words and grammatical constructs, and to avoid circumlocutions and especially idioms.

If people can't understand the simple word 'must' how will they understand the more complicated words that RFC 7322 uses to define it?

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.

This argument doesn't make any sense, because someone who somehow manages to find 'must' ambiguous would also find 'absolute requirement' ambiguous. The RFC doesn't solve the problem, if there is a problem in the first place.

If 'absolute requirement' is clear enough as plain English in a normal sentence, without having to capitalise it, then why isn't 'must' clear enough?

You must not see the value in dictionaries, or explanatory text, or examples at all.

Let me rephrase: would you have a problem with RFC 2119 if it defined the terms P0, P1, and P2? If so, why? (That would be a bizarre stance to me.) If not, why do you see it as problematic that they chose the words MUST, SHOULD, and MAY, instead of P0, P1, and P2? After all, there's no logical fault in choosing more memorable names.

I see this problem in code often too. Some people think it's sufficient to give functions and variables English names with "obvious" meanings. Yet however "obvious" the meaning is to you, it can be interpreted differently by different people because English is ambiguous. Such symbol names without comments ascribing them a meaning plain English might as well just be "xyzzy", "qwert", and "l33t". English-named symbols are mnemonic devices, nothing more.

Example: the code base I work on as two commonly-used functions, "findObject" and "getObject". One returns a reference to an object only if already cached; the other fetches it from disk if necessary. Which does which? Does "find" mean to go out and actively "find" the object? Or is it referring to the fact that it only returns the object if it is "found" in cache? After all "get" is a pretty active verb. I guarantee you, whoever named these (and didn't document them!) thought like you, that the meanings were "obvious" and "unambiguous". And I bet they were, to that person, at that time, in that context.

I for one, can never remember whether SHALL is mandatory or not, or whether SHOULD indicates nice-to-have-but-not-mandatory, or purely optional. They're terrible English words to use in a formal specification. But the mere fact that RFC 2119 disambiguates them as formal terms in the context of specifications makes them eminently usable for that purpose.

No you're missing my point.

These words already have definitions. You can look them up in a dictionary. Or almost all speakers know them anyway.

Why do we need an RFC, and to write them in capital letters?

What does the RFC add to anything? If you removed the capitalisation and the reference to the RFC then your text means exactly the same thing, as the words already had the same meanings.

> English is ambiguous

Well then how does the RFC solve that problem? Their definitions of these terms are using other English words which are also ambiguous.

> I for one, can never remember whether SHALL is mandatory or not

What do you think 'shall' means in a normal conversation? How could it mean anything except mandatory? In what normal English context does 'shall' mean optional?

If a normal person tells you that you must submit your expenses before the end of the month do you get confused about whether it's required or not? If they write it in capitals and refer you to the RFC do you suddenly understand now?

> Well then how does the RFC solve that problem? Their definitions of these terms are using other English words which are also ambiguous.

The same way that a dictionary definition clarifies the meaning of a single English word. By using complete sentences to rule out grey areas.

I see no point in furthering this discussion. Your defeatist assertions like the above "there's no possible way to disambiguate English", your refusal to admit that apparent synonyms such as "must" and "shall" might not be perfect synonyms to people other than yourself, and your repeated sarcasm and snark, suggest to me that you do not see the opposite viewpoint as legitimate, and therefore are not amenable to changing your viewpoint.

> The same way that a dictionary definition clarifies the meaning of a single English word.

Right, so use the dictionary we already have! Why do we need the RFC?

> "there's no possible way to disambiguate English"

This quote isn't from me. I didn't say that - I don't know where you've got it from.

> your repeated sarcasm and snark

Sarcasm and snark? I don't use those rhetorical devices if I can avoid it. I don't think I've used them in this thread at all! I don't know where you've got the idea that I'm not arguing seriously from. I'm sorry I gave that impression.

My legitimate argument is that nobody is honestly confused by words like must - nobody. The RFC is over-the-top formalism where it's not needed.

The RFC is far more useful in dealing with the word "should". It is used in the standards to mean something that is optional but strongly recommended ("there may exist valid reasons in particular circumstances to ignore a particular item"), whereas in english the first definition that comes up is "used to indicate obligation, duty, or correctness".

To me it seems that there could easily be confusion between these two interpretations.

Not sure if your typo was intentional.

You might like the additional followup standard, RFC 6919: 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…)

What's the difference between "OUGHT TO" and "SHOULD"?

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?

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

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.

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.

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?

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?

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.

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.

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.