News for hackers. Stuff that matters.
Re:Undervalued Engineering Skills: Writing Well by jknoepfler on Friday May 31, 2019 @02:41PM (#20063781)
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).
Re:Undervalued Engineering Skills: Writing Well by matwood on Friday May 31, 2019 @04:02PM (#20064428)
> 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."

Re:Undervalued Engineering Skills: Writing Well by technofiend on Friday May 31, 2019 @04:21PM (#20064594)
>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.

Re:Undervalued Engineering Skills: Writing Well by walshemj on Friday May 31, 2019 @02:57PM (#20063933)
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.

Re:Undervalued Engineering Skills: Writing Well by cosmodisk on Friday May 31, 2019 @04:04PM (#20064444)
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.
Re:Undervalued Engineering Skills: Writing Well by catherd on Friday May 31, 2019 @09:00PM (#20066422)
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.

Re:Undervalued Engineering Skills: Writing Well by colanderman on Friday May 31, 2019 @10:33PM (#20066817)
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.
Re:Undervalued Engineering Skills: Writing Well by chrisseaton on Friday May 31, 2019 @03:28PM (#20064140)
If people can't understand the simple word 'must' how will they understand the more complicated words that RFC 7322 uses to define it?
Re:Undervalued Engineering Skills: Writing Well by colanderman on Friday May 31, 2019 @10:24PM (#20066779)
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.

Re:Undervalued Engineering Skills: Writing Well by chrisseaton on Friday May 31, 2019 @11:40PM (#20067099)
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?

Re:Undervalued Engineering Skills: Writing Well by colanderman on Saturday June 01, 2019 @01:22PM (#20070250)
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.

Re:Undervalued Engineering Skills: Writing Well by chrisseaton on Saturday June 01, 2019 @02:02PM (#20070501)
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?

Re:Undervalued Engineering Skills: Writing Well by colanderman on Saturday June 01, 2019 @03:15PM (#20070957)
> 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.

Re:Undervalued Engineering Skills: Writing Well by chrisseaton on Saturday June 01, 2019 @03:20PM (#20070982)
> 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.

Re:Undervalued Engineering Skills: Writing Well by charlieda on Monday June 03, 2019 @08:00AM (#20082241)
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.