I vote for adding a feature that would let people post comments/code snippets to the documentation of other peoples packages :) 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. I've often spent time trying to figure out how poorly documented function(s) on someone else's package worked. Once I've figured it out, I usually have a nice little example or explanation that I could post to save other people the same trouble. Having an easy way to do this would be nice. Basically any collaborative/wikish enhancements to the documentation on hackage packages would make me happy :) - Job On Wed, Apr 7, 2010 at 4:43 AM, Matthew Gruen wrote:

On Wed, Apr 7, 2010 at 12:40 AM, Matthew Gruen wrote:

...

Hi Haskellers,

<snip>

Oh, heh, I apologize if that was more of a wall of text than I had realized. The above wasn't a project proposal itself, more the result of some brainstorming and some research. If you have the time to read it, I'd really appreciate your feedback.

In fewer words, what kinds of features would benefit the community most for Hackage?

/Matt _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe

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.

...

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

On Fri, Apr 9, 2010 at 10:31 AM, Edward Kmett wrote:

On Fri, Apr 9, 2010 at 10:21 AM, 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.

How would such annotations/snippets/changes react to the next release of the package? Would they be per-package? per version?

-Edward Kmett

Yeah that's the sticky part. I think I would make comments only apply only to the version of the package they were submitted to, and then make it the package maintainers responsibility to potentially update the hard documentation with the more useful comments when he/she releases the next version. This keeps the comments up to date, and helps prevent things from getting too clogged up with junk comments. It would also be nice to provide an easy way for maintainers to copy comments from older versions to newer ones, but this is a bit more tricky to implement. - Job

On Fri, Apr 9, 2010 at 10:46 AM, Malcolm Wallace < malcolm.wallace@cs.york.ac.uk> wrote:

...

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?

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 ) - Job

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/)

On Thu, Apr 8, 2010 at 6:38 PM, Matthew Gruen wrote:

On Wed, Apr 7, 2010 at 9:02 AM, Maciej Piechotka wrote:

...

I guess 'works also with B in version X.Y.Z' is also. Most of the above changes should not be IMHO in cabal (sorry for answering PS here). Especially 'not maintained anymore' and 'does not build on recent GHC' ;)

<quote>

As we are with Haddock - 'rebuild' button if package failed to build? For some reasons some packages fails to build on hackage (as yi). I'm not sure if it will work however. At least uploading docs should be possible.

Regards

More flexibility for building times is a good thing, but people shouldn't able to DDOS the server by compiling, since it's a rather CPU-intensive thing, or by building documentation. Now, it looks like yi fails because data-accessor-template fails because of TH versioning issues (seemingly). I like the ideas of docs you can upload to get around these sorts of problems, and the ability to add links to other docs and tutorials. People could edit Hackage to reference haskellwiki, community.haskell.org, and other sites/services.

I see what you mean about the changes being segregated from cabal, and I agree here. There's a set of information that's useful both for the web interface and for cabal-install (which is what Hackage currently displays, although perhaps not enough of it), and that should stay in the .cabal files. But, other information that's user-editable on Hackage is a plus.

One thing in the branch over in http://code.haskell.org/hackage-server is the ability for package maintainers to upload documentation to the server. This way we're not tying the ability of the server doing a build-check to the ability to host documentation for a package. Antoine

On Thu, Apr 8, 2010 at 11:07 PM, Matthew Gruen wrote:

On Thu, Apr 8, 2010 at 10:58 PM, Antoine Latter wrote:

...

One thing in the branch over in http://code.haskell.org/hackage-server  is the ability for package maintainers to upload documentation to the server. This way we're not tying the ability of the server doing a build-check to the ability to host documentation for a package.

Antoine

Antoine, hi, I'm still absorbing the great things that have been done in hackage-server so far. I saw some documentation replacement logic in the code, but don't see a web interface for it. Is there one I'm missing?

There's nothing so useful! The feature is definitely missing proper tool support ,- at the moment there is only a POST request to a particular address. Antoine

On Fri, Apr 09, 2010 at 09:23:51PM -0400, Matthew Gruen wrote:

The proposal as I submitted it is here:

http://docs.google.com/View?docid=0Afa5MxwyB_zYZGhjanNrdjNfMjkzZjloOWNienY&pageview=1&hgd=1&hl=en [...] The work on bringing hackage-server up to feature parity is primary.

Absolutely. I would go further: all the new features (1-3) should be deferred until the new server is not just deployable, but in service. (After all, that's the only way to be sure it really is deployable.) If you can do that, you'll get much more input on the new features when you come to them.