[Haskell-cafe] about documentation improvements

[Gwern Branwen]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

On Fri, Jan 16, 2009 at 9:29 AM, Duncan Coutts  wrote:
> On Fri, 2009-01-16 at 15:12 +0100, Manlio Perillo wrote:
>> About latest thread on better naming and documentation improvement, why
>> don't organize an interactive session where:
>>
>> 1) normal users tell what's wrong about a package/module documentation
>> 2) the package/module author/maintainer fix the documentation in real
>>     time, so that users can review it again
>
>
> Along similar lines, here's a project I've been thinking about that
> someone might like to try...
>
> It's a cross between darcs and a wiki. You want to let users contribute
> minor fixes to code or documentation. It's especially relevant for
> trivial changes to documentation. But instead of making the change live,
> it makes a darcs patch and sends it to the package maintainer.
>
> The point is it should be as easy as a wiki to make some minor
> improvement, but it does not mean your actual source code lives in a
> wiki, the maintainer still has control and gets patches via their normal
> source control system.
>
> Duncan

Now that Gitit supports a Darcs-backend, maybe Gitit would work.

The idea is one would do a darcs get of whatever library, mv it into a
gitit dir/, and then run gitit in dir/. Now there's a web interface
which lets people edit any repo-tracked file (dir/repo/*).

Of course, there's nothing stopping users of that wiki from editing
stuff besides the haddocks (although one certainly hopes they will
stick to doc changes). But here's the cool part: because each wiki
edit is a full-fledged patch, and the wiki's dir/repo/ is presumably
tracking the main library repo, any patch from the wiki should be
directly applicable to the main library repo.

So then someone can, every day or two, visit the wiki and review all
the patches. He obliterates the bad ones, and he will either darcs
push or darcs send all the good ones to the main repo!

This proposal has the advantage of being extremely easy to set up and
run, easy to understand ("this here wiki is an exact copy of the real
repo; if we like your changes, we'll copy them over to the real repo
after a day or 2. Now run along and have fun."), and still permitting
as much review as the conventional lumbering process.

And it also has scope for additional capabilities. Perhaps one would
add a post-commit-hook which does a darcs send of all new patches to a
mailing list. Or perhaps Gitit could display Haskell src files as
Haddock pages only so an editor could make little tweaks, hit the
'preview' button, and see whether he fixed whatever. Or...

- --
gwern
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (GNU/Linux)

iEYEAREKAAYFAklwqZcACgkQvpDo5Pfl1oIxEgCeJkKE+uGsjw2Yb3rIRolaam7e
aagAnR4yDKJ7e3QI8MEzwQtSYT43oPUF
=4JXN
-----END PGP SIGNATURE-----