Write documentation providing articulate description of the *user* model
(not the implementation model), what the user needs to know to be a
"good" darcs users.  Not the manual.

See Git for Computer Scientists

Could be written in an afternoon, perhaps

Note that if you do knock this out, you should (need-action) contact
Simon PJ with a URL so that he can give feedback

http://eagain.net/articles/git-for-computer-scientists/

Git for Computer Scientists documents the internals of git for computer 
scientists ("not scared by words like Directed Acyclic Graph"). You 
mention "what the user needs to know to be a good darcs user". Should 
these be two documents, or one ?

Making it one document is fine.  I would consider the stuff presented in 
Git for Computer Scientists high level enough for this sort of document.  
It's not so much trying to be friendly as concise/comprehensive while 
eschewing unnecessary implementation and theoretical detail.  In other 
words, this is how you the user need to see your repository (even in 
data structure terms), not how Darcs sees it, nor how patch theory 
works.

My take on Simon PJ's comments anyway.  Adding Simon Marlow because he's 
the one who suggested Git for Computer Scientists to illustrate what 
Simon PJ meant when he talked about this.  Plus having three Simon's in 
a BTS ticket is always fun.

I think different people are comfortable with different kinds of
documentation.  In this instance I think the key difference is between
"procedural" documentation ("here's what you do to achieve X") vs.
"declarative" documentation ("a repository has the following properties,
and here are the operations you can perform on it").  I'm pretty sure
you want both, and it doesn't matter if there's overlap between the two.

What I'm after is a "user model".  By that I mean an understanding of
what state Darcs maintains, but in only enough detail for a user to make
sense of.  That's more like what Simon M calls "declarative properties".
Notice that this does *not* mean implementation detail.

Example of what I mean:
* A Darcs repository is a collection of patches
* When you 'record', you add a new patch to your local Darcs repo,
without changing your working files.
* A patch A "depends on" another patch B if (a) B modifies the same
lines as A does, and (b) B was in your repository when you recorded A. 
This is important if you, say, want to get patch A (because then you
must pull B too). Similarly unrecording B entails unrecording A.
* A patch A "conflicts with" a patch B if they both modify the same
lines of a file, but neither depends on the other.

etc

http://en.wikibooks.org/wiki/Understanding_darcs tries to do a bit of 
this.

As a sort of experiment, I tried writing a section of how I understood 
Simons PJ and Marlow at http://wiki.darcs.net/Using/Model.  Is that the 
sort of idea?

I'm a darcs newbie and just finished reading 
http://wiki.darcs.net/Using/Model last night.  I thought it was excellent 
and complete enough for understanding most day-to-day darcs operations.  
I'd personally consider this issue resolved

Thanks for the feedback! I think there are a coule of things that need 
to happen before we can mark this done:
- finish off the story on conflicts
- clean up some of the outstanding TODOs and fact-checks

Unfortunately, I don't see myself getting around to this for a while. 
Help always appreciated.