On Fri, Apr 24, 2009 at 12:06:12AM -0400, David Abrahams wrote:
quoted text >
> 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.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to
majordomo@vger.kernel.org
More majordomo info at
http://vger.kernel.org/majordomo-info.html