Getting our README files decent

[Wayne Schuller <k_wayne linuxpower org>]

hi all, (cc'ed to gnome-love)

Good README files communicate important information. They also give a good 
impression that the tarball is well maintained and professional. An out of date 
README file or NEWS file gives the impression of extreme bitrot.

A good README file should have (inspired from glib/gtk):
Summary of what the module does. Also how it fits into gnome 1 or 2 would be nice.
Reference to the website, the maintainers email, and any mailing list. (I call this admin details)
Dependencies and building information (or a ref to the INSTALL file if it exists).
Any minor/building FAQ's or special notes that prevent common trip-ups.
Notes on the License.
Information on how to submit bugs, feature requests and patches.


I did a quick review of the list of modules I have installed from gnome2:

	esound  	- Dated but OK
	gtk-doc		- Good
	glib		- Excellent
	linc		- Brief
	atk		- Excellent
	gnome-common	- Dated...
	pango		- Excellent.
	libIDL		- Good overview, but missing admin details.
	ORBit2		- Out of date.
	gnome-xml	- Good.
	intltool	- Good but missing admin details.
	bonobo-activation - Seems out of date and missing admin details.
	gtk+		- Excellent.
	gconf		- Good.
	libart_lgpl	- Good.
	libzvt		- Non-existant.
	libbonobo	- Good but out of date gnome 1.x refs.
	gnome-mime-data	- Brief - missing lots of sections.
	gnome-vfs	- Brief - missing bits, a bit dated.
	libglade	- Good, missing admin details. A bit dated.
	libxslt		- Good.
	libgnome	- Non-existant.
	libgnomecanvas	- Non-existant.
	libbonoboui	- Just says: "see libbonobo/README"
	libgnomeui	- Non-existant.
	libwnck		- Out of date, missing most sections.
	librsvg		- Out of date, but has most bits.
	gail		- Good, but missing some admin details. 
	eel		- Good, a bit dated though, sounds like it's for naut 1.0.
	gtkhtml2	- Non-existant.
	libcapplet	- Out of date?
	gtk-engines	- Good. 
	gnome-desktop	- Good but 'use at own risk' sounds like it's not officially used.
	gnome-panel	- One-liner - needs more info.
	gnome-session	- Ok, a bit brief.
	profterm	- A bit negative for something which is now official!
	gnome-utils	- Out of date.
	gnome-applets	- Out of date, missing admin details.
	gnome-control-center - Out of date.
	glade		- Good except out of date refs to gtk 1.2
	gnome-games	- Non-existant.
	bug-buddy	- Ok but could have more info.
	eog		- Good, dated refs to gnome-libs etc.
	nautilus	- Good but itselfs admits it could be more user friendly.
	procman		- Good, missing admin details.
	yelp		- Good, missing admin details.
	gedit		- Incomplete.
	gconf-editor	- one-liner.
	gnome-db	- Good.

I think we could do some work to get these all up to scratch for the release. Remember there will be many outsiders simply downloading tarballs, without any benefit of being on mailing lists already. They need to be able to know what to do, and what each module does. An 'outsider' doesn't know that libgnome is for gnome 2.0 only, or that bug-buddy 2.1/2.2 is for gnome 2, or that libglade2 is for gtk2 etc.

The biggest culprits right now are:
libzvt, libgnome, libgnomecanvas, libgnomeui, libwnck, gtkhtml2, gnome-desktop, gnome-panel, gnome-session, gnome-utils, gnome-applets, gnome-games, gnome-control-center.

Would the maintainers be willing to invite people to write these for them? 
Sounds like a good gnome-love project?

It would be beautiful if all our README's were of glib/gtk quality. Not to mention the NEWS file...

thanks,
wayne