On Fri, Apr 10, 2009 at 01:37:35 +0200, Daniel Carrera wrote: >> In particular, I suggest adding yourself to >> http://wiki.darcs.net/index.html/PatchTheoryPeople >> at some point to help grow the patch theory community > > Me? I'm just a newbie.
Newbieness is useful. It keeps us honest. > I see. I guess the resources are very scattered. There's the Darcs wiki, > Camp, the darcs manual and the wiki book. :-( Yep. My take on it: - the darcs manual is official but old, and missing discussion on darcs 2 - the darcs wiki is broad, but shallow - the wikibook tries to be friendly, but isn't rigorous and probably gets on people's nerves. Plus it's horribly incomplete - the camp documentation is new and quite thorough (although it doesn't explicitly cover darcs 2) - Jason's thesis is clear and introduces the patch theory stuff, but it doesn't go into that much detail > I don't want to make any commitment, but with that understanding, sure. > I'm generally good at writing/organising technical documentation. I just > have too much work to make any commitment. But if you can accept > sporadic, random, unpredictable help, sure. We can accept any help. Trent Buck has been our de-facto documentation manager (he says not ready to make formal commitment yet, but he's been thinking about this stuff the most), so it might be good to coordinate with him. > For starters, where would you like to see the patch theory stuff to be? > Darcs wiki? Camp? Wikibooks? Short answer: the manual Long answer: I believe there are two kinds of work to be done: The first is to cut down on the proliferation of incomplete resources. This could consist of a lot of pruning bits off everything (for example, recognising that some chapters in the wikibook might never be written, and just pointing them to an official source instead), or just marking discussions as being old and obsolete as needed. The second is to flesh out the documentation we have, and this I believe should take place in the darcs user manual. I would love to see this stuff refreshed, for example with modernised notation from Jason's thesis and maybe camp stuff, unified terminology, and the darcs-1 stuff clearly delineated from the darcs-2 stuff. For example, it could start with an overview of patch theory (commutation and merging), and then move on to conflicts and say: here's how we dealt with conflicts in darcs 1, here's how we do it in darcs 2 (the idea being that in the future, we could tack on the camp stuff). I'm not sure what is the right way to go about this. Maybe it could consist of a great merge, pulling in bits and pieces from the newer write-ups like Jason's thesis and newer work like Ian's paper (which does not explicitly describe darcs-2 but covers a lot of the same ground, which sadly the darcs manual does not seem to). The dream is for somebody else to be able to come up and ask "where can I learn about patch theory", and we can point them to the One True Source. I hope I'm not making this sound like too daunting a task! If this kind of shake down is too hard, there is still a lot of on-and-off gardening we need doing. I'm just trying to sketch one of my patch theory dreams out and hope that somebody else can up with a plan. What do you think? -- Eric Kow <http://www.nltg.brighton.ac.uk/home/Eric.Kow> PGP Key ID: 08AC04F9
pgpa5zh8jmEOL.pgp
Description: PGP signature
_______________________________________________ darcs-users mailing list [email protected] http://lists.osuosl.org/mailman/listinfo/darcs-users
