[Haskell-cafe] Re: GSoC: Hackage 2.0

[Job Vranish]

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.


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

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

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.

- Job
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.haskell.org/pipermail/haskell-cafe/attachments/20100409/b1a5689e/attachment.html