[darcs-users] manual/latex vs api docs/haddock

[Trent W. Buck]

Simon Michael <simon at joyful.com> writes:

> Here's what I came with chatting on irc:
>
> - haddock for documenting functions and types
>
> - the manual for everything else, including theory, developer
> introduction and resources, etc.

My view is that the manual (which I have been calling the "user manual"
to be clear) is specifically targeted at end users.  That is, people who
run darcs, rather than people who hack on darcs or write third-party
code to manipulate Darcs repositories.

I'm happy for more developer-oriented stuff to be appendices of the user
manual, but I think there should be a clear emphasis, particularly in
the early chapters, on people who "just wanna use Darcs".

If there's enough material, it might be appropriate to split off the
developer-y stuff into a separate LaTeX manual, though I think much of
it would be more appropriately bundled with haddock.

There are certainly cases where other modules have had e.g. example code
or a general description of the package as part of the haddock HTML
bundle... I don't know how much support haddock has for general
developer documentation that isn't specifically API documentation...