On Tue, Sep 08, 2009 at 12:48:25AM +0100, Chris Lamb wrote: > But would such a pointer be valuable enough to mitigate these concerns? For > a newbie, the answer might very well be "yes". However, this seems like a > weak and relatively rare case to optimise for, compounded by the high cost > of excessive false-positives. I'm not sure I share those concerns. In the long run, the only person whom you write documentation for is, in fact, the newbie. The difference is only that the definition of 'newbie' varies. Anyone who hasn't seen a quilt-using package yet, will be helped by a README.source that explains there's this documentation over there which explains how quilt is supposed to be used. Anyone who hasn't seen a Debian package yet, will be helped by the dpkg-source manpage that explains how to run 'dpkg-source -x' to get at the source. Anyone who hasn't used git yet, will be helped by an introductory page on how to use it. Anyone who hasn't seen this particular package yet, will be helped by a three-page README.source explaining how the source is laid out. In all the above cases, the person who's reading the documentation is a newbie. The first is a quilt newbie; the second a Debian packaging newbie; the third a git newbie; and the last a newbie to a particular package. While it might be perfectly reasonable to assume people will just read every bit of documentation in every package that they've got installed on every computer that they've ever used, I'd tend to think it'd be more useful if we were to assume that isn't the case. As such, a standard piece of documentation that explains what to do, and/or has pointers to where the actual documentation is, is still useful -- even if it isn't anymore to those of us who've seen it all a hundred times. -- The biometric identification system at the gates of the CIA headquarters works because there's a guard with a large gun making sure no one is trying to fool the system. http://www.schneier.com/blog/archives/2009/01/biometrics.html
Attachment:
signature.asc
Description: Digital signature