[Scheme-reports] distributed repository: README.txt doc as package requirement

[John Gabriele <jmg3000@x>]

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
Scheme-reports@x
http://lists.scheme-reports.org/cgi-bin/mailman/listinfo/scheme-reports