[darcs-users] Separating the user manual and code

Eric Kow kowey at darcs.net
Wed Oct 22 09:11:08 UTC 2008


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.

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.

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

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

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

-- 
Eric Kow <http://www.nltg.brighton.ac.uk/home/Eric.Kow>
PGP Key ID: 08AC04F9
-------------- 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/20081022/5221f41c/attachment.pgp 


More information about the darcs-users mailing list