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

15 Jan 2014

      ...
-----Original Message-----
From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Rob Stewart
Sent: Wednesday, January 15, 2014 1:52 AM
To: boost@lists.boost.org
Subject: Re: [boost] [git] annotated SVN synchronization for boost.test (example only)
On Jan 14, 2014, at 12:51 PM, "Paul A. Bristow"  wrote:
...
...
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.
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.