Alex S. recently posted about a distributed repository and call for names. I'd like to suggest that, as part of whatever package format is chosen (I'll assume "Snow/snowball/snowfort" for the following discussion), that the presence of a README file (written in some format easily convertible to html ([Pandoc's enhanced Markdown][1] would be my suggestion)) be a requirement.
This is because: * A package (er, snowball) with at least *some* documentation is arguably much more valuable to prospective users than one without any. * You're going to have major problems getting adoption by users (people downloading snowballs to use them in their projects) if they can't at least browse a README to see if the library is what they want. * Most users uploading to the snowfort (snowmen?) would probably write a README for their library anyway. * Requiring at least a README sends a positive message to the community that the intent is for everyone to easily be able to learn about and make use of others' packages. * A snowball's README (converted to html) can be displayed online at the snowfort (and also indexed by search engines). This is what's usually done at Python's Cheeseshop (PyPI), though the procedure's not automated. * Perl users are used to being able to read all of a package's docs online before installing the package (via search.cpan.org). This includes docs embedded into modules as well as standalone docs. This is enormously useful. If a snowball didn't provide at least a README for the snowfort to display, it would not compare well with the current competition. Much appreciation to Alex S. for his work on this. (BTW, after writing this message, I'm liking the name "Snow" more and more. For example, it would be fun to read about "heavy snowfall this month!" (large number of snowballs added/updated), and use a tool named snowman (actually, maybe that tool would be used for reading snowball man pages...). Would uploading a snowball with the same name as an existing one lead to a snowball fight? :) ) ---John [1]: http://johnmacfarlane.net/pandoc/ _______________________________________________ Scheme-reports mailing list [email protected] http://lists.scheme-reports.org/cgi-bin/mailman/listinfo/scheme-reports
