[development] Documenting contribs

[inkfree press]

"Moshe Weitzman" wrote:

> I like reuse of .info files because it centralizes project metadata. We
> probably need some more metadata fields.

An excellent point.  (One file to rule them all. One file to bind them.)[*]

The problem is:  Out of 354 modules just checked, only _3_ use this file at
all:

    refresh.info
    kml.info
    georss.info


So, there's that.


The general guideline of including an "INSTALL.txt", "README.txt" and
"LICENSE.txt" is a very wobbly guideline also.  Some have only the last,
some have a README.txt which has only one sentence, saying "See some other
document named blah" or similar.  And some have files named without any
extension at all [README].

A common, required and re-usable system should be able to avoid some of the
call for a "Golden Seal" stamped onto some modules, indicating their level
of quality.  (I _still_ think that's a worthy system, but that debate was
long and generally a non-starter.)

-- 
inkfree

[*] Plain text format with metadata labels (as it is) is excellent and
re-usable in lots of ways.  This should be taken advantage of, of course.  I
agree that there need to be more "label =" metadata data fields.  Everthing
should be here, and then it can be used to auto-generate the module
description pages.  Even whole "Module Library" descriptions could be
downloaded in XML, for browsing descriptions.  Yes, one well-formed file
should be the basis of everything else -- maintainers only need to keep one
".info" source and that's it.