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

Subject: Re: [boost] [git] annotated SVN synchronization for boost.test (example only)
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2014-01-15 05:40:01

> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Rob Stewart
> Sent: Wednesday, January 15, 2014 1:52 AM
> To: boost_at_[hidden]
> Subject: Re: [boost] [git] annotated SVN synchronization for boost.test (example only)
> 
> 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.

After you've done it once, won't you use just remember the commands anyway ;-)

Paul

PS Yes - of course - but it's much more work, and I'm not sure how with a wiki 'language' - or
Quickbook.

So while we are all newbies at modular-boost, I think we need all the help we can get.