[darcs-users] darcs patch: Edit Front Page (and 9 more)

Stephen J. Turnbull stephen at xemacs.org
Mon Apr 13 16:24:48 UTC 2009


Daniel Carrera writes:

 > Stephen J. Turnbull wrote:
 > > To be blunt, I suggest <nothing> is better than "smart patch" or
 > > "patch commutation", because they are claims that we can't
 > > substantiate to the potential user
 > 
 > This comment really confuses me. AFAIK "commutation" is precisely the 
 > correct term. Patch commutation is the source of patch algebra. Patch 
 > algebra (AFAIK) is just patch commutation.
 > 
 > I understand if you feel that "commutation" is too mathematical (I might 
 > disagree, but I understand). But I don't understand when you say that we 
 > can't substantiated.

I didn't say that.  I said we can't substantiate *to the potential
user*, because she doesn't have a clue what we're talking about.

Of course "commutation" *is* precisely the right term if we're talking
to a sophisticated user.  But they're not the ones the home page is
needs to be designed to attract.

 > In particular, I don't see how "ordering" can be more easily
 > substantiated than "commutation".

"I go first!"  Even a two-year-old understands "order".  But most
people think of "commute" as that painful 45 minutes between the
apartment and the office.  We're asking a lot of the new user to
understand the technical term "commutation".  Sure, you can define it,
but I don't think it help them understand the benefits of Darcs to
them.  Doing task A then B, or B then A, at *your* option rather than
the VCS's, is a concrete benefit that I think users completely
unfamiliar with VCSes will be able to understand.

 > Putting this issue aside, if you like the term "patch reordering"

Unfortunately, my point is that I don't like *any* unfamiliar terms on
the top few pages.  I think I wrote that "human programmers think of
patches as implementing features, they don't want to worry about what
order to do apply them.  Darcs lets you forget all that (as much as
possible, anyway, and it prompts you with what to do next)."  Or
something like that.

 > I don't object to your phrasing, and I'll be happy to bulk copy from 
 > what you wrote. That said, I think that it is useful to have a short, 
 > simple term to crystallize the feature in people's minds.

Sure.  I like "patch theory" or "patch algebra" for that, though.

To my mind the problem with "patch commutation" or "patch reordering"
is that the nice thing about Darcs is that you rarely think about
them.  The frenetic rebasing that kernel developers do is one of the
things that turns many people off of git.  *Not* having to think about
that is a good reason "Why Darcs?"  IMO naming it emphasizes it too
much.

 > > So, the general principles I'm advocating here are that (1) people
 > > are going to find the identification of "implementation of behavior
 > > features" with "patch set" *intuitive*, and
 > 
 > Personally I don't think that emphasizing "sets" vs "sequences" will 
 > help. I think that a lot of people would find that simultaneously 
 > obscure and mathematical. Just say that darcs can apply patches in any 
 > order.

Sure.  That's what I did in the 25-line version, didn't I?  Trying to
compress it into a single 5-line bullet point, well, you're right.
It's overly technical to contrast sets vs. sequences of patches, and
that whole sentence could be dropped with little loss of meaning.

 > Do notice that I have been trying to suggest alternate ways to convey 
 > what makes darcs special without saying "patch theory". Please give me 
 > some credit for that.

Well, I'm of the opinion that mentioning the words "patch theory" once
on the front page is not a totally bad idea.  Sure, spin control is
important.  Any hint of a suggestion that effective use of Darcs
requires knowing something about patch theory or quantum physics is
going to kill the interest of a lot of potential users, it's true.
But saying that patch theory was used to develop a VCS that allows the
user to safely merge in the changes that they want when they want them
is like saying that your QA department runs the program through a
battery of 20000 tests before every release.  Nobody wants to hear the
details, but they feel better about the product.

If you think that you can do an effective job of describing the
benefits of patch theory without using any technical terms or the
words "patch theory", great!  No need for spin control, then.

 > We wouldn't be having this discussion if it weren't because I
 > decided to help with documentation and remove patch theory from the
 > front page.

Sure.  I'm glad you're doing the work, so is everybody else.  And you
should remember that (with some input from Eric and I guess Trent) "he
who does the work makes the decisions," you can ignore my suggestions
in the final product and you'll hardly even hurt my feelings.

But I just have the feeling that trying to come up with a buzzword to
replace "patch theory" is doomed to fail, because they're all about
implementation details that potential users don't really want to hear
about, yet.  Then, once they are new users sliding down the ol'
learning curve toward advanced, they will want to hear about patch
reordering and the primitive operation commutation, and that whole
discussion can be said to be about "patch theory" without chasing
anyone away.  But that should be about two clicks away from the top
page, IMO.



More information about the darcs-users mailing list