[Haskell-cafe] Re: GSoC: Hackage 2.0

[Nick Bowler]

On 10:21 Fri 09 Apr     , Job Vranish wrote:
> On Fri, Apr 9, 2010 at 9:46 AM, Ivan Lazar Miljenovic <
> ivan.miljenovic at gmail.com> wrote:
> 
> > Job Vranish <job.vranish at gmail.com> 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 <malcolm.wallace at cs.york.ac.uk> 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/)