[darcs-users] Separating the user manual and code

Trent W. Buck trentbuck at gmail.com
Wed Oct 22 23:26:19 UTC 2008


On Wed, Oct 22, 2008 at 10:11:08AM +0100, Eric Kow wrote:
> A third argument is that the user's manual serves as code
> documentation for hackers.  It gives us a "feel" for where we are in
> the code.

I think that's a separate "deliverable" to the user manual, namely the
API documentation.

> Anyway, if you are willing to do the work and if you are willing to
> commit to taking charge of the user's documentation (with the usual
> right to delegate of course!), then I will enthusiastically support
> the move (as long as we do it carefully).

I'm certainly happy to work on it; depending on how easily I take to
it I might be able to then take on a full documentation manager role.
My main concern has been overcommitting, time-wise.

Moving forward from here, the work involved is

- transcribing the user manual hunks from src/foo.lhs to
  doc/manual/foo.tex and making sure the manual still builds.  At the
  same time, I should be able to point out any non-manual literate
  bits that warrant haddockification.

- getting consensus on what source format to use (Max and I favour
  reST, though I don't know if Max wants to get involved in ongoing
  maintenance of the user manual).

- translating doc/manual/foo.tex into that other format, and making
  sure the manual still builds.

- [ongoing] integrating regular "update the manual to match updates to
  the code" passes with the wider release procedures, so that stable
  releases always have accurate documentation, even if its sometimes
  out of date in the unstable repo.

I'll aim to get started on the first point this weekend.


More information about the darcs-users mailing list