[darcs-users] darcs patch: Refactor Darcs homepage. (and one more).

[Guillaume Hoffmann]

First, a global remark: some ideas you want to convey in the home page
belong (in my opinion) more to behind-the-scene discussions, the kind
that happen on this mailing list and IRC. But these ideas do not bring
to potential users a clear idea of what benefit one has to use darcs.
We have to take into account the short attention span of someone who
visits the homepage, yet we want to turn thel into a darcs user.

I don't know the magic formula to create the best darcs propaganda,
but from my experience with colleagues, I can tell that there are a
few "darcs facts" that they do NOT care about:

* being around since 2002 (CVS was around since longer,is it better ?)
* being written in Haskell
* being written by a physicist
* involving an algebra of patches
* being written by honest, skeptical, humble, and audacious people (in
one word: scientists :-) )

People want something that *works*. That's all. Then a subset of users
have more prerequisites, like using free software, using a maintained
software, using a software used by a lof of people...

My rule of thumb is that all of this should not belong to the a first
presentation of darcs.
What are the experience of other people on this list with
darcs-agnostic people ?

> I was trying to say "we were doing dVCS before most people realized it
> was a good idea.  Our other ideas are good, but nobody else realizes
> it yet".

This would belong more to a "Darcs vs other DCVS" wiki page. I feel a
direct confrontation with other DCVSes does not belong to a homepage.
Sounds defensive.

> The point I was trying to convey with those bits is that
>
>  - we're using mathematics!  Which automatically makes us better than
>   the competition, because
>
>  - they are just doing whatever seems like a good idea at the time.

Users are more interested by the outcome than by the way it works internally.

See for instance
http://www.3ofcoins.net/2008/12/16/darcs-vs-git-mathematician-versus-engineer/

>   However,
>
>  - though the internals are very clever, you don't have to be very
>   clever to use Darcs.

I agree with you on this, and I think this is the only place where we
should allude to darcs' internals.

> That third point is similar to people saying "I don't use Haskell
> because I don't understand monads!"  I have the impression that some
> people avoid Darcs merely because they've *heard* of patch theory, and
> think that you need a maths degree in order to use Darcs.

Yep, that's a pity, but I think the darcs team itself is responsible
for this perpection.

> As for "improving", while I don't understand patch theory properly, my
> impression is that the darcs-2 format exists because we (the
> community) found out that the darcs-1 implementation was "wrong" --
> like how dynamic scoping came about because Minsky didn't (initially)
> understand the lambda calculus.  And "we're improving" is meant to
> lead into camp/darcs-3, i.e. "we can do even better!"

It's honest to say it, but once again, it is hard to formulate this in
a short discourse without having people thinking:
"Hmm so what are they going to break in the next 6 months ?". And then
if you go as far as mentioning darcs' different repository formats,
people are scared. (I do not have empirical proof of this, but this is
quite scary in theory, right ?).

>> Easy to use
>>
>> Darcs only requires to learn a simple set of commands and takes care
>> of the details by itself.
>
> I might change "easy to use" to just "simple", although that might
> have the wrong connotation.

OK so let's stick to "easy to use". Extreme concision is not the
single way to go.

>> I don't like it: "we think that" sounds unsure.
>
> Would "we believe" carry more conviction?  I wanted to capture the
> feeling of the camp video: "we continue to develop darcs/camp because
> we believe it's better".

Once again, behind-the-scenes discussion.

> While this perception is widespread, I'm not convinced that it's
> actually true.  I wanted to gently challenge that assumption by
> implying that maybe 1) git/hg get attention because they're "new kids
> on the block"; and 2) maybe that disparaging Darcs review you read in
> 2004 doesn't apply anymore.
> [...]
>
> I also wanted to work a mention of our competitors in there somewhere,
> because it shows that we aren't just stubbornly barreling on down a
> dead end -- we are aware of those competitors and want to steal their
> good ideas.
>
> It also acts contrariwise to our user manual, which until very
> recently talked as if our main competitors were CVS and Arch -- which
> makes us look stuck in the past.

What about putting a link to a wiki page "darcs vs other DCVSes" in
the "User Resources" section ?

guillaume