[darcs-users] Separating the user manual and code

David Roundy droundy at darcs.net
Sat Oct 25 15:07:59 UTC 2008


On Wed, Oct 22, 2008 at 10:11:08AM +0100, Eric Kow wrote:
> Briefly: I have a soft spot for the literate Haskell as user's manual
> approach, but I also think that Trent is probably right on this one.

Briefly:  I'm answering a few of your comments here, and will respond more
fully to Trent in a separate email.

> This is part of a recent darcs trend in re-evaluating and simplifying
> our infrastructure.  We want to make it easier for people to contribute.
> 
> On Wed, Oct 22, 2008 at 15:27:20 +1100, Trent W. Buck wrote:
> > Arguments for mixing the user manual with the source code:
> > 
> >   If there's no dedicated documentation team, then the only people who
> >   can keep the user manual up to date are the hackers themselves.
> >   Mixing the user manual and the source code help hackers remember to
> >   update the manual as they update the code.
> > 
> >   Updating the user manual and the code in the same patch has some nice
> >   consequences when cherry-picking patches; the user manual is never
> >   "wrong" or out of date.
> 
> 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.  On the
> other hand, I suspect I am the only one here who really feels this way,
> and that other developers are more distracted by the blobs of LaTeX than
> anything else.
>
> Below are my favourite arguments from Trent's list for separating out
> the user's manual:
> 
> >   It's unusual for people to be good at both hacking and technical
> >   writing.  If technical writers are available to work on the user
> >   manual, then it'd be better to let the hackers do what they do best.
> 
> I find this very convincing.

I am unconvinced that techincal writers are unable to edit literate source
code.

> >   Using separate files means that the user manual can be arranged
> >   differently to the underlying code modules.  You can already see this
> >   done for some sections of the user manual that don't have
> >   corresponding code in src/*.tex. There's also some clever code to
> >   arrange the "Darcs commands" section into some logical subsections
> >   that doesn't occur with the source modules.
> 
> The user's manual is a bit of a tangle with the
> current approach.  Simpler is simpler.  

There are certainly sections that make sense to arrange differently in
source and in the manual.  But the bulk of the manual is documentation of
the darcs commands, and these work

> >   This clearly separates API documentation (which is targeted at other
> >   hackers) from user documentation (which is targeted at end users, who
> >   just want to run darcs, not change it).  For example, the "Introduction"
> >   section at the top of Lcs.lhs is really API documentation.
> 
> Actually, even if we do not separate the manual, we should probably push
> for all the API-style documentation to be haddocks.  Literate Haskell
> should probably only be used for user's manual and explaning theory at
> most.

Agreed about not using literate stuff for API docs.

> >   Lastly, Emacs isn't very good at handling two very different languages
> >   (like Haskell/TeX or XHTML/Javascript) in a single file, and tools
> >   like literate-haskell-mode or mumamo only partially address this. :-)

I've found mmm-mode works pretty nicely.

> I concede that it probably will be a relief to have just straight
> Haskell in Vim.
> 
> 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).
> 
> Thanks!
> 



> _______________________________________________
> darcs-users mailing list
> darcs-users at darcs.net
> http://lists.osuosl.org/mailman/listinfo/darcs-users


-- 
David Roundy
http://www.darcs.net
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
Url : http://lists.osuosl.org/pipermail/darcs-users/attachments/20081025/59d3d1be/attachment.pgp 


More information about the darcs-users mailing list