Re: [boost] [git] annotated SVN synchronization for boost.test (example only)

Subject: Re: [boost] [git] annotated SVN synchronization for boost.test (example only)
From: Rob Stewart (robertstewart_at_[hidden])
Date: 2014-01-14 20:52:20

On Jan 14, 2014, at 12:51 PM, "Paul A. Bristow" <pbristow_at_[hidden]> wrote:

>> From: Boost [mailto:boost-bounces_at_[hidden]] 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)