Re: [Haskell-cafe] Package descriptions on hackage
On 12 September 2011 23:29, Ryan Newton wrote: > On Sun, Sep 11, 2011 at 1:14 PM, wren ng thornton wrote: >> >> On 9/11/11 6:37 AM, Neil Mitchell wrote: >>> >>> Why not email the maintainers of packages you think need a better >>> description - ideally giving suggestions? I'd welcome that for any of >>> my packages. >> >> +1. >> > > +1 > Actually this thread itself is helpful. It made me cringe and realize I was > guilty. In my/our case I think we just overlooked it. I just realised from you mentioning this that I only added to the description of graphviz that it's for graph visualisation in the releases I made last month... in my defence, this had been added in the darcs repo a while ago, but I hadn't made a release in so long... -- Ivan Lazar Miljenovic ivan.miljeno...@gmail.com IvanMiljenovic.wordpress.com ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Package descriptions on hackage
On Sun, Sep 11, 2011 at 1:14 PM, wren ng thornton wrote: > On 9/11/11 6:37 AM, Neil Mitchell wrote: > >> Why not email the maintainers of packages you think need a better >> description - ideally giving suggestions? I'd welcome that for any of >> my packages. >> > > +1. > > +1 Actually this thread itself is helpful. It made me cringe and realize I was guilty. In my/our case I think we just overlooked it. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Package descriptions on hackage
On Sun, Sep 11, 2011 at 13:14, wren ng thornton wrote: > On 9/11/11 6:37 AM, Neil Mitchell wrote: > >> Why not email the maintainers of packages you think need a better >> description - ideally giving suggestions? I'd welcome that for any of >> my packages. >> > > +1. > > Of course, requiring feedback in order to improve places an undue burden on > the users; the maintainers should be trying to save users from that labor. > But everything has to start somewhere. > Not to mention that not all users can actually help there; I'm still smarting a bit after hitting the functional lenses package and bouncing hard (even after digging out and reading the paper, which made more sense than the haddock...). -- brandon s allbery allber...@gmail.com wandering unix systems administrator (available) (412) 475-9364 vm/sms ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Package descriptions on hackage
On 9/11/11 6:37 AM, Neil Mitchell wrote: Why not email the maintainers of packages you think need a better description - ideally giving suggestions? I'd welcome that for any of my packages. +1. I always love to hear that my packages are useful to someone. And if someone says "hey this is useful, but here's something to make it even more useful" that's awesome. Of course, requiring feedback in order to improve places an undue burden on the users; the maintainers should be trying to save users from that labor. But everything has to start somewhere. -- Live well, ~wren ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Package descriptions on hackage
On Sun, 2011-09-11 at 11:37 +0100, Neil Mitchell wrote: > There are several problems here: [..] > Why not email the maintainers of packages you think need a better > description - ideally giving suggestions? I'd welcome that for any of > my packages. Maybe something similiar to http://kernelnewbies.org/KernelJanitors could be done, e.g. "HackageJanitors". Those HackageJanitors could also help making new GHC releases smoother by providing efficiently the usual minor fixes to hackage libraries breaking by new GHC releases (updating library version constraints, fixes related to GHC becoming less tolerant, adapting to Cabal changes). Maybe they could also be given the privilege to upload trivial fixes to hackage directly (possibly with a version indicating such a maintainer-override upload) if the library maintainer takes too long to respond or has generally opt-ed in for to such a "auto"-maintaince service (maybe by a new flag in .cabal files). cheers, hvr ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Package descriptions on hackage
There are several problems here: 1) Not everyone can write beautiful clear English descriptions, it takes a certain skill. 2) The person writing the description is the author, who knows all the details, but the person reading the description doesn't - writing for a different audience is an even harder skill to master. 3) It's easy to miss something when updating a package. 4) Quality documentation places an ongoing maintenance burden on the package, and while test suites etc. make code maintenance easy, I don't know any way to automatically check documentation! Why not email the maintainers of packages you think need a better description - ideally giving suggestions? I'd welcome that for any of my packages. Thanks, Neil On Mon, Sep 5, 2011 at 11:22 PM, Ivan Lazar Miljenovic wrote: > On 5 September 2011 23:59, Joachim Breitner wrote: >> Dear hackage package authors, >> >> this is a short message from your distribution package creators: Please, >> if possible, write good, not too short descriptions, and also keep them >> up to date. Of course, users browsing hackage will benefit as well. > > Also for potential users trying to work out what your library does! > > Something that I find particularly frustrating is all the libraries of > the form "hFoo: Haskell bindings to the Foo library"; well, what _is_ > the Foo library? > > -- > Ivan Lazar Miljenovic > ivan.miljeno...@gmail.com > IvanMiljenovic.wordpress.com > > ___ > Haskell-Cafe mailing list > Haskell-Cafe@haskell.org > http://www.haskell.org/mailman/listinfo/haskell-cafe > ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Package descriptions on hackage
On 5 September 2011 23:59, Joachim Breitner wrote: > Dear hackage package authors, > > this is a short message from your distribution package creators: Please, > if possible, write good, not too short descriptions, and also keep them > up to date. Of course, users browsing hackage will benefit as well. Also for potential users trying to work out what your library does! Something that I find particularly frustrating is all the libraries of the form "hFoo: Haskell bindings to the Foo library"; well, what _is_ the Foo library? -- Ivan Lazar Miljenovic ivan.miljeno...@gmail.com IvanMiljenovic.wordpress.com ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Package descriptions on hackage
Dear hackage package authors, this is a short message from your distribution package creators: Please, if possible, write good, not too short descriptions, and also keep them up to date. Of course, users browsing hackage will benefit as well. Keep in mind that the users do not know what other packages this relates to. So if the package is part of a larger set of corresponding packages, include a general blob and then explain this particular packages. This is especially true for packages that contain the base types for a suite of packages. Also think about all the possible keywords that someone might enter in a search engine when looking for something like your package, and ideally explain how your library relates to these keywords so that the user can estimate whether it useful for him even before reading the API. Here a few negative examples, not to expose particular authors, but selected because they were the most resent that the Debian Haskell Team had packaged. = The http-enumerator package This package uses attoparsec for parsing the actual contents of the HTTP connection. The only gotcha is the withHttpEnumerator function, otherwise should do exactly what you expect. (A list of supported features would be great, maybe a short note what enumerator means. Also, the second sentence is incomprehensible to me and the latest version does not contain a withHttpEnumerator function any more) = The representable-functors package Representable functors (Clearly not helpful. Here is what Iulian came up for for the Debian package, from the individual module documentation, but I still think the author could do better This package provides a generalized Store comonad, parameterized by a Representable functor (the representation of that functor serves as the index of the store) and a generalized State monad, parameterized by a Representable functor (the representation of that functor serves as the state). Representable functors on Hask all monads, being isomorphic to a reader monad. Representable contravariant endofunctors over the category of Haskell types are isomorphic to (_ -> r) and resemble mappings to a fixed range. Representable endofunctors over the category of Haskell types are isomorphic to the reader monad and so inherit a very large number of properties for free.) = The data-lens package Haskell 98 Lenses (Also not helpful. And probably a very useful package! Iulian wrote „A lense is a composable notion of a purely functional field accessor.“ which is still quite short, but explains the use of the package much better) = The algebra package Constructive abstract algebra (Seems to be the “main” package of a series of packages. Yet another reason for having a good description. Here a suggestion, again by Iulian: “This package provides algebraic structures, such as groups, fields, rings, modules. It also provides bands, also known as idempotent semigroups (band is a semigroup where every element is equal to its own square), coalgebras, semirings (rigs), idempotent semirings, also known as dioids.“) = I know that most people have better things to do than to write API documentation, so it is not unexpected that, after having written the API documentation after all, they don’t spend too much time on the description. But think about it: It is the first thing possible users are going to see from your package. So if you want to attract users, do take your time to write a comprehensive and comprehensible description. Thanks, Joachim -- Joachim "nomeata" Breitner m...@joachim-breitner.de | nome...@debian.org | GPG: 0x4743206C xmpp: nome...@joachim-breitner.de | http://www.joachim-breitner.de/ signature.asc Description: This is a digitally signed message part ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
