I hate to bitch but bitch I must

Steve Bertrand steve at ibctech.ca
Sat Oct 17 00:00:44 UTC 2009

PJ wrote:
> Polytropon wrote:
>> On Fri, 16 Oct 2009 17:54:23 -0400, PJ <af.gourmet at videotron.ca> wrote:

>>> but from man tunefs:
>>> BUGS
>>> This utility should work on active file systems.
>>> What in hades does this mean--just above it says cannot be run on active
>>> file systems. ???
>> It "should". This means: Don't try that. :-)
>> My printer isn't printing!
>> But it should.
>> No, it is not printing!
>> Yes, but it should.
>> :-)
> Aha! Gotcha! Whoever wrote that has made an unintentionnal booboo. It is
> a subtle difference and is indicative that whoever wrote it is not a
> native english user... the meaning is clearly "should be executed, done,
> carried out, performed" - should work means it  can be carried out  - I
> think the author meant to say "should not be done"

If you feel that you've found a 'bug' within the manual/documentation of
a piece of software or function, I highly recommend that you pass it by
other users/developers ( as you've kind-of done here ), and then contact
the person who is normally listed in the AUTHOR section of the man page
after you get a consensus on whether the manual, the code or you have
the bug :)

If you believe the problem is an engish-linguistic one (and the man page
is written in english), let the author know this. Provide the correct
verbiage, and an explanation of what your words mean compared to theirs
(remember, english may not be their first language).

Also, take a look at RFC 2119 for the keyword 'SHOULD' and 'SHOULD NOT'.
RFC 2119 is highly regarded as the authority for many keywords, and a
quick reference of it may help when trying to explain to an author where
you feel their documentation is incorrect (or lacking).



More information about the freebsd-questions mailing list