Re: [doc] User Manual Suggestion

["J. Bruce Fields" <bfields@fieldses.org>]

On Fri, Apr 24, 2009 at 12:06:12AM -0400, David Abrahams wrote:
>
> On Apr 23, 2009, at 10:29 PM, J. Bruce Fields wrote:
>
>> On Thu, Apr 23, 2009 at 01:37:05PM -0500, Michael Witten wrote:
>>> On Thu, Apr 23, 2009 at 12:57, J. Bruce Fields  
>>> <bfields@fieldses.org> wrote:
>>> Why don't the docs start out defining blobs and trees and the object
>>> database and references into that database? The reason everything is
>>> so confusing is that the understanding is brushed under the tutorial
>>> rug. People need to learn how to think before they can effectively
>>> learn to start doing.
>>
>> OK, but let's not over-generalize: the person that just wants to  
>> figure
>> out whether the driver for their network card was fixed in today's
>> network devel tree shouldn't have to sit through a discussion of the
>> object database.
>
> Those people don't need a VCS.  They should download a snapshot or use a 
> web interface.  Seriously.  There's no way you can make even the  
> best-designed VCS simple enough to justify the time it takes to learn  
> enough just to use it for that.
>
>> And even among readers that are in it for the long
>> haul, I think many people will react better to something that gives  
>> them
>> at least a little concrete how-to information up front.
>
> People (well, people like me) should get a brief "hello, world" demo up 
> front, to give them a feel for the flavor of the system, but  
> [important:] it shouldn't attempt to be instructive.  Fundamental  
> concepts are next.  How-to information can come after that, or after the 
> reference information.
>
>> So the goal was always to find a tutorial route through the material
>> that would allow us to introduce the concepts as we go along.
>
> Maybe that will work for some people, but it *really* won't work for me.  
> You can't start throwing around terms of art without defining them unless 
> you want to raise more questions than you're answering.  I would be 
> surprised if it wasn't the same for many tech people.

I agree that (with rare exceptions) terms shouldn't be used before
they're defined.  I don't agree with all of the above, but I think we
could come to a satisfactory compromise.  I'll see if I can find a few
hours this weekend to at least sketch a new organization.  But, as I've
said, I'm short on time and could really use some help.

--b.