Re: [Gnu-arch-users] Re: "Newbie-ized help"

[Matthew Palmer]

On Mon, Sep 27, 2004 at 06:02:15PM -0400, John S. Yates, Jr. wrote:
> 
> "Stefan Monnier" <address@hidden> writes:
> 
> > > I'm sure it is a killer feature :) What I'm not so sure about is: Is it
> a
> > > newbie feature? Would newbies, typically coming from a CVS background,
> use
> > > star-merge constructively, or are they better off with update? I ask,
> > > because I don't know.
> >
> > I *never* use update.
> > Instead, I just use `tla star-merge --three-way' which works just like
> > CVS does.
> 
> No one is going to find his way to arch simply as a replacement for CVS.
> If that is all he seeks SVN is just too polished and prominent for arch
> to compete.  To my mind he will investigate arch for one of two reasons:
> 
> 1) distributed development
> 
> 2) changeset orientation
> 
> That being the case the newbie help should expose enough functionality
> for our newbie to have a satisfying experience with either methodology.
> You are undercutting the argument for arch if you encourage habits that
> later have to be broken in order to experience arch's true power.

I'll second that, primarily because that was exactly how I came to choose
Arch over SVN.  CVS was sucking harder than it needed to, and I was going to
switch to SVN, until Robert Collins "showed me the light" as it were, and
those two features above (along with the ability to remember what patches
had been applied) were the features I was most interested in.

In that vein, I don't know if the mirroring commands are necessarily a bad
thing to have in the newbie help, but I can certainly see the reasoning for
leaving them out.  Basically, I think that if a command is intuitive or
simple enough to be able to document usefully in the 25 lines or so you've
got in a single standard screen, then it's a candidate for the newbie help. 
If it's going to require a fair bit of explanation, like the concept of
mirroring, then it's likely that you don't want to put it in the newbie
help, but rather point them to a tutorial or equivalent.

Of course, I haven't applied my criteria to the help, so it might end up
that the list of commands that meet the criteria evaluates to []...

- Matt

signature.asc
Description: Digital signature