Not to beat a dead(?) horse, but I found quite early that the ReadMe is *the* place to go to find out what is in the latest version. Honestly, I think the coverage of all changes and updates going back 10 years may be overkill, but the value is definitely there. I agree with both Scotts: I think that it is important to focus on the development of the product, but also to provide sufficient explanation of new features that are released. You have to have balance - if you focus only on the product but don't provide sufficient documented changes, you significantly frustrate your users, and if you focus on great docs but minimal advancement, you significantly frustrate your users. :-)
That said, I don't think this is a matter of development vs. documentation; this only becomes a problem if the developers themselves are responsible for the documentation. I have worked with quite a few companies where there was one or more people who were assigned to documentation and support, and did not impede the progress of the development of the product. Perhaps all that is necessary is identifying someone who fits that bill (whether in-house or a consultant)? Just my $0.02, Ken Ray Sons of Thunder Software Email: [EMAIL PROTECTED] Web Site: http://www.sonsothunder.com/ ----- Original Message ----- From: "Scott Rossi" <[EMAIL PROTECTED]> To: <[EMAIL PROTECTED]> Sent: Tuesday, January 29, 2002 1:14 PM Subject: Re: Release notes and bug reports (was Re: Geometry Manager) > > 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 > _______________________________________________ improve-revolution mailing list [EMAIL PROTECTED] http://lists.runrev.com/mailman/listinfo/improve-revolution
