On Jan 14, 2014, at 12:51 PM, "Paul A. Bristow"
From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Peter A. Bigot
On 01/14/2014 11:00 AM, Beman Dawes wrote:
The problem, of course, is that your procedure is overwhelmingly complex for a new git user. That's why the docs we've been working on try to stick to very basic git.
True. The problem with the docs is that they don't explain what the commands are doing and why (or why not) use them.
Rote application works until something goes wrong, then people get confused about what happened.
Definitely - this is a serious flaw with very, very many sets of instructions.
* They don't say why the next step is being taken.
* They don't say how one can tell it has worked OK.
* Or how to check that it has worked OK.
* And what to do if it hasn't.
[snip]
I know this makes the instructions longer but IMO it's well worth it.
Explanations and rationales are always a good idea, but after one is familiar with the process, but enough time elapses to need the instructions again, one wants just the instructions. I suggest links to pop-ups, or to separate pages, that provide the details while not cluttering the sequence of commands. ___ Rob (Sent from my portable computation engine)