[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
> 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