One problem with using the README file as the synopsis is that a lot of the standard information in a README file would be out of place when displayed on hackage. For example, many READMEs have: * installation instructions * a list of contributors * a list of known bugs * how to contribute bug reports * licensing information Some of this information is very out of place on hackage, some of it is duplication of the standard fields in the cabal file, and some of it is just not things that a new user needs to see on their first visit to the package documentation. Maybe this could be solved by having the name of the synopsis file as a variable the author can specify. It can default to README(.md) but can be overridden to something else for authors who choose to do so. On Tue, Sep 16, 2014 at 11:20 PM, Mike Izbicki wrote:

One problem with using the README file as the synopsis is that a lot of the standard information in a README file would be out of place when displayed on hackage. For example, many READMEs have:

* installation instructions * a list of contributors * a list of known bugs * how to contribute bug reports * licensing information

Some of this information is very out of place on hackage, some of it is duplication of the standard fields in the cabal file, and some of it is just not things that a new user needs to see on their first visit to the package documentation.

Maybe this could be solved by having the name of the synopsis file as a variable the author can specify. It can default to README(.md) but can be overridden to something else for authors who choose to do so.

On Tue, Sep 16, 2014 at 8:58 PM, Michael Snoyman wrote:

...

On Wed, Sep 17, 2014 at 12:10 AM, Richard Lewis wrote:

...

So there's clearly an important technical hurdle to be overcome for this: what markup language is to be used?; and where should the synposis be stored?

But I can't help thinking that the real work is in getting the synopses written. Encouraging package authors/maintainers to add them to their own packages is one possible way forward.

Actually, if we get the README support in place, I think it should be much easier to get package authors to write synopses. Most projects have a README file already, and getting it included in Hackage would now be a one-line pull request (adding `extra-source-files: README.extension`). It will hopefully be easier to get authors to elaborate on their READMEs then because:

1. They're serving double duty, both in the project repository and on Hackage. 2. It's trivial for outside developers to send pull requests against a simple text file. I've received quite a few such contributions on projects I maintain, even from people not ready to work on the code itself.

...

At Mon, 15 Sep 2014 11:28:38 -0700, Tikhon Jelvis wrote:

...

Maybe we could have a guerrilla campaign of pull requests adding examples and a bit of explanation to every package you like that doesn't have them... That could also be a good way for beginners who want to contribute to start.

Another, as Tikhon suggests, would be for others to write them and send pull requests (or whatever) to the maintainers.

At Mon, 15 Sep 2014 20:10:18 -0400, Dominick Samperi wrote:

...

I think this is a great idea, but it probably needs a complementary "nudge" if it is going to have a significant impact. This could be incorporated into the package submission process where the submitter runs a final check and is warned when examples are not provided for exported functions (unless an "opt out" flag is turned on for functions that have "obvious" semantics).

And yet another, as Dominick suggests, is effectively to require a synposis when a package is submitted. In CPAN, it's just become part of the culture, but it's also not required and you do find packages without a synposis.

If there's interest, I'd like to solicit some discussion on this part of the proposal on this thread...

There may also be a potentially significant difference between Hackage/Haskell and CPAN/Perl: most CPAN packages tend to be quite small and specific in their purpose and consequently have just a few, simple common use cases which suit a synposis very well. Hackage packages, on the other hand, are quite often more broad in their scope, often comprising many modules. Also, Perl has only one semantics for organising code at the finest level: sequential, imperative statements. In Haskell, some packages actually define whole coding styles. As a result, it's always pretty obvious how to write a few isolated lines of Perl code, but not necessarily so with Haskell code. Anyway, I'm sure all this can be overcome, and/or argued against.

Richard -- -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- Richard Lewis j: ironchicken@jabber.earth.li @: lewisrichard http://www.richardlewis.me.uk/ -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- _______________________________________________ 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