Re: [doc] User Manual Suggestion

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

quoted

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