From brooks@minya.sea.one-eyed-alien.net  Tue Jul 18 09:34:13 2000
Return-Path: <brooks@minya.sea.one-eyed-alien.net>
Received: from minya.sea.one-eyed-alien.net (minya.sea.one-eyed-alien.net [216.39.168.226])
	by hub.freebsd.org (Postfix) with ESMTP id 352F337B633
	for <FreeBSD-gnats-submit@freebsd.org>; Tue, 18 Jul 2000 09:34:12 -0700 (PDT)
	(envelope-from brooks@minya.sea.one-eyed-alien.net)
Received: (from brooks@localhost)
	by minya. (8.9.3/8.9.3) id XAA10468;
	Mon, 17 Jul 2000 23:13:54 -0700 (PDT)
	(envelope-from brooks)
Message-Id: <200007180613.XAA10468@minya.>
Date: Mon, 17 Jul 2000 23:13:54 -0700 (PDT)
From: brooks@one-eyed-alien.net
Sender: brooks@minya.sea.one-eyed-alien.net
To: FreeBSD-gnats-submit@freebsd.org
Subject: [PATCH] the FAQ needs an entry on bikesheds
X-Send-Pr-Version: 3.2

>Number:         20009
>Category:       docs
>Synopsis:       [PATCH] the FAQ needs an entry on bikesheds
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    alex
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Tue Jul 18 09:40:01 PDT 2000
>Closed-Date:    Wed Jul 19 03:11:32 PDT 2000
>Last-Modified:  Wed Jul 19 03:11:54 PDT 2000
>Originator:     Brooks Davis
>Release:        FreeBSD 5.0-CURRENT i386
>Organization:
>Environment:

>Description:

People are confused by all the refrences on hackers, etc. to the color
of bikesheds.  There should be a FAQ about this.

>How-To-Repeat:
>Fix:

Apply this patch in the faq directory and add a man entity for sleep(1).
Hopefully, this doesn't contain too many DocBook style errors.  I think
I recal Nik saying that patches should follow the style guide not the
status quo in the FAQ.

Index: book.sgml
===================================================================
RCS file: /home/ncvs/doc/en_US.ISO_8859-1/books/faq/book.sgml,v
retrieving revision 1.70
diff -u -r1.70 book.sgml
--- book.sgml	2000/07/11 21:36:22	1.70
+++ book.sgml	2000/07/18 05:50:06
@@ -8782,6 +8782,85 @@
 
 </answer></qandaentry>
 
+      <qandaentry>
+	<question>
+	  <para>Why should I care what color the bikeshed is?</para>
+	</question>
+
+	<answer>
+	  <para>The really, really short answer is that you shouldn't.
+	    The somewhat longer answer is that just because you are
+	    capable of building a bikeshed doesn't mean you should stop
+	    others from building one just because you don't like the
+	    color they plan to paint it.  This is a metaphor indicating
+	    that you need not argue about every little feature just
+	    because you know enough to do so.  Some people have
+	    commented that the amount of noise generated by a change is
+	    inversely proportional to the complexity of the
+	    change.</para>
+
+	  <para>The longer and more complete answer is that after a very
+	    long argument about whether &man.sleep.1; should take
+	    fractional second arguments, Poul-Henning Kamp posted a long
+	    message entitled <quote><ulink url="http://www.FreeBSD.org/cgi/getmsg.cgi?fetch=506636+517178+/usr/local/www/db/text/1999/freebsd-hackers/19991003.freebsd-hackers">A
+	    bike shed (any colour will do) on greener
+	    grass...</ulink></quote>.  The appropriate portions of that
+	    message are quoted below.</para>
+
+
+	  <blockquote>
+	    <title>Excerpts from <quote>A bike shed (any colour will do) on
+	      greener grass...</quote></title>
+
+	    <attribution>Poul-Henning Kamp on freebsd-hackers, October
+	      2, 1999</attribution>
+
+	    <para>"What is it about this bike shed ?" Some of you have
+	      asked me.</para>
+
+	    <para> It's a long story, or rather it's an old story, but
+	      it is quite short actually.  C. Northcote Parkinson wrote
+	      a book in the early 1960'ies, called "Parkinson's Law",
+	      which contains a lot of insight into the dynamics of
+	      management.</para>
+
+	    <para>[snip a bit of commentary on the book]</para>
+
+	    <para>In the specific example involving the bike shed, the
+	      other vital component is an atomic power-plant, I guess
+	      that illustrates the age of the book.</para>
+
+	    <para>Parkinson shows how you can go in to the board of
+	      directors and get approval for building a multi-million or
+	      even billion dollar atomic power plant, but if you want to
+	      build a bike shed you will be tangled up in endless
+	      discussions.</para>
+
+	    <para>Parkinson explains that this is because an atomic
+	      plant is so vast, so expensive and so complicated that
+	      people cannot grasp it, and rather than try, they fall
+	      back on the assumption that somebody else checked all the
+	      details before it got this far.   Richard P. Feynmann
+	      gives a couple of interesting, and very much to the point,
+	      examples relating to Los Alamos in his books.</para>
+
+	    <para>A bike shed on the other hand.  Anyone can build one
+	      of those over a weekend, and still have time to watch the
+	      game on TV.  So no matter how well prepared, no matter how
+	      reasonable you are with your proposal, somebody will seize
+	      the chance to show that he is doing his job, that he is
+	      paying attention, that he is *here*.</para>
+
+	    <para>In Denmark we call it "setting your fingerprint".  It
+	      is about personal pride and prestige, it is about being
+	      able to point somewhere and say "There!  *I* did that."
+	      It is a strong trait in politicians, but present in most
+	      people given the chance.  Just think about footsteps in
+	      wet cement.</para>
+	  </blockquote>
+	</answer>
+      </qandaentry>
+
 <qandaentry><question>
 <para>How many FreeBSD hackers does it take to change a lightbulb?</para></question><answer>
 


>Release-Note:
>Audit-Trail:

From: Sheldon Hearn <sheldonh@uunet.co.za>
To: brooks@one-eyed-alien.net
Cc: FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Re: docs/20009: [PATCH] the FAQ needs an entry on bikesheds 
Date: Tue, 18 Jul 2000 18:49:03 +0200

 On Mon, 17 Jul 2000 23:13:54 MST, brooks@one-eyed-alien.net wrote:
 
 > People are confused by all the refrences on hackers, etc. to the color
 > of bikesheds.  There should be a FAQ about this.
 
 Personally, I'd just give a reference to phk's original message.
 
 Ciao,
 Sheldon.
 

From: Brooks Davis <brooks@one-eyed-alien.net>
To: Sheldon Hearn <sheldonh@uunet.co.za>
Cc: brooks@one-eyed-alien.net, FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Re: docs/20009: [PATCH] the FAQ needs an entry on bikesheds
Date: Tue, 18 Jul 2000 10:10:33 -0700

 On Tue, Jul 18, 2000 at 06:49:03PM +0200, Sheldon Hearn wrote:
 > On Mon, 17 Jul 2000 23:13:54 MST, brooks@one-eyed-alien.net wrote:
 > > People are confused by all the refrences on hackers, etc. to the color
 > > of bikesheds.  There should be a FAQ about this.
 > 
 > Personally, I'd just give a reference to phk's original message.
 
 The problem with that is that it won't work in print on offline.  I don't
 think it's very helpful to have FAQ entries that don't directly give
 some sort of useful answer unless it's really not possiable.
 
 -- Brooks
 
 -- 
 Any statement of the form "X is the one, true Y" is FALSE.
 

From: Sheldon Hearn <sheldonh@uunet.co.za>
To: Brooks Davis <brooks@one-eyed-alien.net>
Cc: FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Re: docs/20009: [PATCH] the FAQ needs an entry on bikesheds 
Date: Tue, 18 Jul 2000 19:11:29 +0200

 On Tue, 18 Jul 2000 10:10:33 MST, Brooks Davis wrote:
 
 > The problem with that is that it won't work in print on offline.  I don't
 > think it's very helpful to have FAQ entries that don't directly give
 > some sort of useful answer unless it's really not possiable.
 
 Ah yes, good point.
 
 Ciao,
 Sheldon.
 

From: Ben Smithurst <ben@FreeBSD.org>
To: brooks@one-eyed-alien.net
Cc: FreeBSD-gnats-submit@freebsd.org
Subject: Re: docs/20009: [PATCH] the FAQ needs an entry on bikesheds
Date: Tue, 18 Jul 2000 19:17:30 +0100

 brooks@one-eyed-alien.net wrote:
 
 > People are confused by all the refrences on hackers, etc. to the color
 > of bikesheds.  There should be a FAQ about this.
 
 I'm starting to think we'll need a "FreeBSD Jargon" section of the FAQ
 soon.  We'd only really have four things to put it in for now though
 (MFC, repo-copy, bike shed, fairings) so I don't think it's worth it
 yet.  OTOH, the kernel config part only has four questions, so perhaps
 we could.
 
 > +	    <para>"What is it about this bike shed ?" Some of you have
 
 I'd use &ldquo;...&rdquo; instead of "..."
 
 [I think that's right, it's either &[lr]dquo; or <quote>, not ".."
 anyway.  I think the last agreement was &[lr]dquo;.]
 
 > +	      paying attention, that he is *here*.</para>
 
 Perhaps <emphasis>foo</emphasis> instead of *foo*, or something.  The
 FAQ isn't limited to ASCII text like email is. :-)
 
 Other than that, this should probably go in the FAQ soon.  I'll fix
 those minor things and maybe commit it soonish.
 
 /me adds it to TODO list.
 
 -- 
 Ben Smithurst                 / ben@FreeBSD.org / PGP: 0x99392F7D
 FreeBSD Documentation Project /
 

From: Brooks Davis <brooks@one-eyed-alien.net>
To: Ben Smithurst <ben@FreeBSD.org>
Cc: brooks@one-eyed-alien.net, FreeBSD-gnats-submit@FreeBSD.org
Subject: Re: docs/20009: [PATCH] the FAQ needs an entry on bikesheds
Date: Tue, 18 Jul 2000 12:18:49 -0700

 On Tue, Jul 18, 2000 at 07:17:30PM +0100, Ben Smithurst wrote:
 > brooks@one-eyed-alien.net wrote:
 > 
 > > People are confused by all the refrences on hackers, etc. to the color
 > > of bikesheds.  There should be a FAQ about this.
 > 
 > I'm starting to think we'll need a "FreeBSD Jargon" section of the FAQ
 > soon.  We'd only really have four things to put it in for now though
 > (MFC, repo-copy, bike shed, fairings) so I don't think it's worth it
 > yet.  OTOH, the kernel config part only has four questions, so perhaps
 > we could.
 
 That might not be a bad idea.  The question in my mind is where
 do glossary entries stop (MFC and repo-copy seem to me to be those)
 and where do FAQ entries begin (bikeshed and fairings have significant
 context in their defination).
 
 > > +	    <para>"What is it about this bike shed ?" Some of you have
 > 
 > I'd use &ldquo;...&rdquo; instead of "..."
 > 
 > [I think that's right, it's either &[lr]dquo; or <quote>, not ".."
 > anyway.  I think the last agreement was &[lr]dquo;.]
 
 I'm almost certain it was decided to do it the other way so quote
 characters would be automagicaly matched and localized properly.
 The problem was that quote styles aren't even consistant withing the
 same language.  For instance, I've got at least one book published in
 the UK that uses quotes that look kinda like >>foo bar baz<< (except
 there are specific quote characters.
 
 > > +	      paying attention, that he is *here*.</para>
 > 
 > Perhaps <emphasis>foo</emphasis> instead of *foo*, or something.  The
 > FAQ isn't limited to ASCII text like email is. :-)
 
 I though of doing that, but it's quoted text.  We could do that, but
 I'd want to be sure that the * (or similar) emphasis marks where being
 added in the text version.  I don't know what w3m does.
 
 > Other than that, this should probably go in the FAQ soon.  I'll fix
 > those minor things and maybe commit it soonish.
 
 Thinking about it some more, I think I'd also strike the <title> text
 from the blockquote.  It's redundent and the rendering in HTML looks
 kinda stupid IMHO.
 
 -- Brooks
 
 -- 
 Any statement of the form "X is the one, true Y" is FALSE.
 

From: Ben Smithurst <ben@FreeBSD.org>
To: Brooks Davis <brooks@one-eyed-alien.net>
Cc: FreeBSD-gnats-submit@FreeBSD.org
Subject: Re: docs/20009: [PATCH] the FAQ needs an entry on bikesheds
Date: Tue, 18 Jul 2000 20:42:58 +0100

 Brooks Davis wrote:
 
 > I'm almost certain it was decided to do it the other way so quote
 > characters would be automagicaly matched and localized properly.
 
 yep, you're right.  I just checked some CVS logs.  That means a couple
 of things I added recently are wrong.
 
 I guess I could put &[lr]dquo; -> <quote></quote> on my list of things
 to cleanup in the FAQ then.  As well as "foo", 'foo', `foo', ``foo'',
 and $DEITY only knows how many other quoting styles are used.
 
 >>> +	      paying attention, that he is *here*.</para>
 >> 
 >> Perhaps <emphasis>foo</emphasis> instead of *foo*, or something.  The
 >> FAQ isn't limited to ASCII text like email is. :-)
 > 
 > I though of doing that, but it's quoted text.  We could do that, but
 > I'd want to be sure that the * (or similar) emphasis marks where being
 > added in the text version.  I don't know what w3m does.
 
 It doesn't add "*" in the text version.  How important is that?  I'd
 argue that removing that is just changing formatting and is no worse
 than re-wrapping the lines or changing "foo" to <quote>foo</quote>.
 *foo* is going to come out real ugly in HTML. :-(
 
 -- 
 Ben Smithurst                 / ben@FreeBSD.org / PGP: 0x99392F7D
 FreeBSD Documentation Project /
 

From: Brooks Davis <brooks@one-eyed-alien.net>
To: Ben Smithurst <ben@FreeBSD.org>
Cc: Brooks Davis <brooks@one-eyed-alien.net>,
	FreeBSD-gnats-submit@FreeBSD.org
Subject: Re: docs/20009: [PATCH] the FAQ needs an entry on bikesheds
Date: Tue, 18 Jul 2000 14:13:39 -0700

 On Tue, Jul 18, 2000 at 08:42:58PM +0100, Ben Smithurst wrote:
 > >>> +	      paying attention, that he is *here*.</para>
 > >> 
 > >> Perhaps <emphasis>foo</emphasis> instead of *foo*, or something.  The
 > >> FAQ isn't limited to ASCII text like email is. :-)
 > > 
 > > I though of doing that, but it's quoted text.  We could do that, but
 > > I'd want to be sure that the * (or similar) emphasis marks where being
 > > added in the text version.  I don't know what w3m does.
 > 
 > It doesn't add "*" in the text version.  How important is that?  I'd
 > argue that removing that is just changing formatting and is no worse
 > than re-wrapping the lines or changing "foo" to <quote>foo</quote>.
 > *foo* is going to come out real ugly in HTML. :-(
 
 I guess that's reasionable.  I'd say it's a bug that emphasis is dropped
 in the ASCII mode, but that you're right in that we should either clean
 the text up to look like normaly formatted DocBook text or include it in
 the DocBook equivalent of <pre> tags.
 
 There's a cleaned up diff with "'s and *'s replaced at:
 
 http://www.one-eyed-alien.net/~brooks/FreeBSD/bikeshed.diff
 
 -- Brooks
 
 -- 
 Any statement of the form "X is the one, true Y" is FALSE.
 
Responsible-Changed-From-To: freebsd-doc->alex 
Responsible-Changed-By: alex 
Responsible-Changed-When: Wed Jul 19 01:32:15 PDT 2000 
Responsible-Changed-Why:  
I'll add it 

http://www.freebsd.org/cgi/query-pr.cgi?pr=20009 
State-Changed-From-To: open->closed 
State-Changed-By: alex 
State-Changed-When: Wed Jul 19 03:11:32 PDT 2000 
State-Changed-Why:  
Entry added, thank you! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=20009 
>Unformatted:
