Date: Sun, 14 Oct 2001 20:30:02 -0700 (PDT) From: swear@blarg.net (Gary W. Swearingen) To: freebsd-doc@freebsd.org Subject: Re: docs/31271: rl(4) discourages vender openness by disparaging remarks. Message-ID: <200110150330.f9F3U2935746@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
The following reply was made to PR docs/31271; it has been noted by GNATS. From: swear@blarg.net (Gary W. Swearingen) To: Dima Dorfman <dima@trit.org> Cc: FreeBSD-gnats-submit@freebsd.org Subject: Re: docs/31271: rl(4) discourages vender openness by disparaging remarks. Date: 14 Oct 2001 20:25:49 -0700 Dima Dorfman <dima@trit.org> writes: > "Gary W. Swearingen" <swear@blarg.net> wrote: > > >Description: > > > > rl(4) discourages device manufacturer's openness > > ... or encourages them to write better documentation :-). Maybe, but I'd rather risk more poor documentation than risk no more documentation. Besides, one can make the point without being insulting about it, and keep both risks lower. > > --- /tmp/rl.4.old Sun Oct 14 15:51:07 2001 > > +++ /tmp/rl.4 Sun Oct 14 15:51:47 2001 > > @@ -189,9 +189,6 @@ > > The driver probably should not be > > depending on this characteristic. > > .Pp > > -The RealTek data sheets are of especially poor quality: the grammar > > -and spelling are awful and there is a lot of information missing, > > -particularly concerning the receiver operation. > > One particularly > > important fact that the data sheets fail to mention relates to the > > way in which the chip fills in the receive buffer. > > If you think this is rude, I invite you to read the first paragraph of > the third comment block of the source code (sys/pci/if_rl.c). It > says, in part: "This is probably the worst PCI ethernet controller > ever [made]". What your change removes is much more polite, albeit > more visible. Further, your change takes away the context from the > sentence following it. Not enough context to worry about. About the only thing removed besides the insults is redundant anyway. The existence of data sheets is mentioned in the "See Also" section. The whole "Bugs" section should be moved to the source code and both purged of insults which do no good and can only do harm. I see nothing in the bugs section that's useful to a user and so don't see that any of it belongs in the User Manual, let alone rants on RealTek's documents. Thanks for reading my own little rant. To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200110150330.f9F3U2935746>