Re: [doc] User Manual Suggestion
- From
David Abrahams <dave@boostpro.com>
- Date
- Apr 27, 2009, 01:41 UTC
- Message-ID
- <m2ab62g9fg.fsf@boostpro.com>
- In-Reply-To
- <20090426222532.GA12338@atjola.homenet>
on Sun Apr 26 2009, Björn Steinbrink <B.Steinbrink-AT-gmx.de> wrote:
Show 11 quoted lines
>> 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