Re: [doc] User Manual Suggestion

[David Abrahams <dave@boostpro.com>]

on Sun Apr 26 2009, Björn Steinbrink <B.Steinbrink-AT-gmx.de> wrote:

>> I think this is why Git remains more opaque than it should be.  You
>> can't assume that people will naturally develop the smartest possible
>> mental model of a VCS, even with faced with some hints in the form of
>> a partial understanding of Git.
>
> I don't think I understand what you mean here. If users don't understand
> the data model, that's caused by missing/bad documentation or because
> the user doesn't want to read the existing documentation. (I'll make no
> assumptions here, it's been some time since I had a close look at the
> docs). But I've been talking about how the given implementation stores
> data in the repository. Could you explain?

You don't have to "not want to read the documentation" to have an
incomplete mental model.  The mental model development doesn't happen
upon finishing the documentation; it happens while the person is
learning.  Halfway through the docs, I have an incomplete mental model.
If you make it hard enough for me, maybe I never finish and I retain
that incomplete model forever.  The more you can help people avoid
incorrect assumptions as they read along, the easier it will be for them
to grok the next bit they are reading, and the less likely they are to
become discouraged.

-- 
Dave Abrahams
BoostPro Computing
http://www.boostpro.com