Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

It's not that unambiguous. Compare "You must not do X" and "You need not do X". The sentences have the same form, and they are both common and idiomatic, but in the second sentence, the "not" modifies "need".


"Need not" isn't exactly common phraseology/is older phraseology, though; and a common way to phrase a similar sentence would be "You do not need to do X", and it's more clear that "not" modifies "need" in that context. Regardless, for a native speaker it should be pretty clear what both mean.


"Need not do ...": Unnecessary.

"Must not do ...": Disallowed / prohibited.


These used to be called Dos and Don'ts.

Do A, B, C. Don't do X, Y, Z.

Am I the only person who thinks it's ironic that an article about documentation appears to suffer from a fairly fundamental ambiguity?


No.

"Need not" (or "May...") indicate actions or behaviours which are allowed or optional. This is not the same as "do X", which is a "MUST" condition.

"Must not" (or "Don't...") indicate actions or behaviours which are expressly disallowed.

RFC 2119 referenced in the article should make all this clear. If you're still confused after reading that ... you SHOULD NOT be writing documentation. And possibly not be reading it ;-)




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: