[darcs-devel] Re: darcs patch: RT #255 Comprehensible shell test output (and 2 more)

[David Roundy]

Thanks Mark, for the perl explanations!

On Sat, Mar 12, 2005 at 09:42:30PM +0000, Mark Stosberg wrote:
> There's also a more general conversation to be had about managing the
> growing documentation, especially the relationship between the wiki docs
> and the manual docs. But I don't have any specific proposals about that
> right now. :)

Indeed.  My feeling on where to draw the line is that things that are
code-specific, *should* be documented in the code, while things that are
general principles or ways of working, may as well be documented on the
wiki, although eventually the manual also ought to have decently complete
"getting started", and "how to use darcs" sections--which perhaps could
migrate from the wiki.

But information that is intricately related to the code--that is,
description of the behavior of certain commands, or the API of Test::Darcs,
should (ideally) be documented literately within the code itself, which
means going into the manual.

Adding a "contributing to darcs", or an "internals" section to the manual
is definitely a good idea.  Probably this should go in an appendix. 
-- 
David Roundy
http://www.darcs.net