[darcs-users] Website - New Revision

[Dan Pascu]

On Friday 17 April 2009, Daniel Carrera wrote:
> Hello,
>
> I finished another round of changes, which includes the migration to
> reST + HTML. In light of the fact that the wiki is off-line, I have
> made a static-HTML mockup so at least there is something for you to
> look at:
>
> http://darcs.daniel.carrera.bz/

The first sentence on that page reads:

<quote>
Darcs is a free, open source, source control manager (SCM). Darcs stands 
out for its ability to reorder patches in a repository. This gives darcs 
several valuable features:
</quote>

after which you list a number of features, each with a short description:

Flexible
Distributed
Human Friendly
Reliable
Easy

This makes it sound like the patch reordering capability is responsible 
and its the foundation for all these features, which is not true.

IMO, patch reordering should not be the first thing to say about darcs in 
a description that is meant as an introduction. The first thing I did 
when I read that sentence was to press on the patch reordering link to 
find out what it means. I expect any 1st time visitor to do this because 
it is an unfamiliar term and it's also suggested that all the features 
listed below are based on it. So naturally a reader tries to clarify the 
concept.

I ended up in a page where I could find some detailed information on the 
subject, but by doing this I failed to read the short description on 
darcs from the first page and I found myself deepening into some fairly 
advanced notions about patch commutation without having a clue if I'm 
interested in what darcs has to offer or not.

IMO, the description of the features should come first, all put in simple 
layman terms without involving the need to define any new concepts. Only 
after that terms like patch commutation or reordering should be 
introduced and the reader should get an explanation on what they are and 
how they constitute the foundation on which those darcs features are 
built upon.

Another similar confusing thing is this sentence from the description of 
the "Human friendly" feature:

<quote>
This makes many "complicated" mergers not complicated at all in Darcs.
</quote>

This uses a concept (merger) that was not yet defined to the reader, 
leaving him confused. The presence of quotes around the word complicated 
also suggests that the word is used loosely adding more to the confusion.

Also, as a personal opinion, I think reliable is not something that needs 
to be advertised as a feature explicitly. I do not know anyone that would 
use a VCS that is not reliable. This feature is implicit in any VCS by 
its nature. This is a bit like saying that the water is wet. Maybe a 
better term to use for this is "consistent", but it has more or less the 
same problems.

Every feature presented is not mandatory. I mean people use VCSs that can 
lack one or more of these listed features: flexible, distributed, human 
friendly or easy. SVN is not distributed, but widely used. GIT is neither 
easy nor human friendly yet used by many. None however, will use a VCS 
that is not reliable/consistent in its behavior.

And a last note: the description for flexible and human friendly overlaps 
quite a bit. They basically describe the same thing in different words.

-- 
Dan