about documentation improvements
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 Manlio Perillo
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
-----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-----
Duncan Coutts ha scritto:
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.
That's what I was thinking, documentation behind a revision control system. However I was thinking of: - normal user can only add "annotations" - only authors can change the documentation
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.
I was not thinking of a wiki; but of a system to be used for small sessions (about 1/2 hour) held once in a while, where there is strong interaction between users and authors. Manlio Perillo
On Fri, Jan 16, 2009 at 03:12:21PM +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
Not quite real time, the documentation generated by the nightly builds should be at http://www.haskell.org/ghc/dist/current/docs/libraries/index.html It doesn't seem to have been updated since 7 Jan, though.
participants (4)
-
Duncan Coutts -
Gwern Branwen -
Manlio Perillo -
Ross Paterson