On Tuesday, January 29, 2002, at 10:20 AM, Scott Raney wrote:
> First of all, we've generated a README file for MetaCard with each new > release going on 10 years now that lists major new features and > incompatibilities introduced. But despite this being a very important > and useful document, we find that few people read it. Increasing its > size by an order of magnitude or more by documenting every tiny little > change or bug fix will make it pretty much useless even to those few > who read the READMEs now. Scott, I would like to respond to the "value" of the README file, which I believe is significant. As someone who has been guilty of missing items included in past README files, it took me a couple of releases to learn that this was the best source of information to find out what has added in the latest version and what has been changed/fixed. Obviously you are aware of the repeated requests on the various mail lists asking for public bug lists and reporting; I think many people have the expectation to find some "Special Secret Important FAQ" posted on a site, rather than realizing most of what they want to know was included with the archive they just downloaded. I would also say that each user's perception of what constitutes a "tiny little change or bug fix" is subjective. I don't know how any one person can decide what is or is not important for users to know. On a related note, I would offer a README criticism: some of the information included in past READMEs could have been more thorough or provided samples of code usage, etc. A personal example was/is the documentation of the latest image properties: a description of the properties has been provided, but no explanation of how to use them. On your end, if you feel that the README is becoming too long, you might consider separating the latest and and greatest info out from the previous README info. Most every large software company offers a "What's New In This Version..." document or something similar. While I personally appreciate being able to reference past and present changes in a single document, splitting up the document may be more to your liking. (Sorry -- doing away with the documents all together is not an option. :-) The bottom line (for me anyway) is that the existence and location (and value) of the README may need to be pounded into people's heads several times, but it is something we definitely need to have. Thanks & Regards, Scott Rossi Creative Director, Tactile Media [EMAIL PROTECTED] http://www.tactilemedia.com _______________________________________________ improve-revolution mailing list [EMAIL PROTECTED] http://lists.runrev.com/mailman/listinfo/improve-revolution
