Re: [Haskell-cafe] Re: GSoC: Hackage 2.0

On 10:21 Fri 09 Apr , Job Vranish wrote:

On Fri, Apr 9, 2010 at 9:46 AM, Ivan Lazar Miljenovic < ivan.miljenovic@gmail.com> wrote:

...

Job Vranish writes:

...

I vote for adding a feature that would let people post comments/code snippets to the documentation of other peoples packages :)

You mean turn every hackage project page into a mini wiki?

Yep.

My worry with this is that users will fill carefully written documentation with irreverent nonsense or, worse, factual errors. Moderation seems necessary.

...

...

It would be even nicer if you could post comments to individual haskell definitions on the haddock page, and then hide most of them by default under an expander of some sort.

Rather than, you know, providing the maintainer with a patch with some improved documentation?

This is often more difficult than it sounds. The biggest obstacle to this approach is that a new hackage version of the package must to be uploaded to update the documentation and the authors (me included) tend to prefer to push new packages only when there are significant changes.

It seems to me that the solution to this particular problem is to allow package maintainers to publish updated documentation separately from new packages.

Steps involved currently: 0. pull down package source to build manually 1. add documentation/code snippet to source 2. build haddock documentation 3. debug bad/ugly syntax / missing line breaks that break haddock 4. generate a patch 5. email patch to author 6. wait a week for the author to actually get around to applying the patch to whatever repository the source resides 7. wait several weeks for the author to release the next version of the package

I suspect that most maintainers are amenable to simple emails containing change requests where documentation is concerned ("please change the first sentence of bazify's documentation to ..."), which means you can skip steps 0 through 4.

Steps involved with mini wiki: 0. add [code] [/code] tags (or whatever) 1. copy 2. paste 3. submit

I think making this process easier would greatly increase the community involvement in the generation of documentation and improve the quality of the documentation as a whole.

I would imaging that this would not be a trivial task, but I think even something super simple (like what they have for the php documentation) would be much better than nothing.

PHP's comments are a fine example of what I *don't* want to see polluting my documentation. There is very little signal to be found amongst that noise.

On Fri, Apr 9, 2010 at 10:46 AM, Malcolm Wallace wrote:

...

How much cooler it would be, if the wiki-like comment on Hackage could automatically be converted into a darcs/git/whatever patch, and mailed to the package author/maintainer by Hackage itself.

This would indeed be awesome :)

Though I think I would prefer to select, from a list of comments, which ones I would like to include, and then click the "Download darcs/git/whatever patch" button. (rather than get hit by emails )

The resulting patches will be patently useless, because the only sort of changes they can make is to append bullet points to existing documentation. Unless you are proposing that users can perform any change whatsoever on hackage? -- Nick Bowler, Elliptic Technologies (http://www.elliptictech.com/)