On Mon, 2003-01-20 at 16:06, Stuart Donaldson wrote: > So Ian, > Specifically what are you suggesting then on having in, and not in for > distributions? > > Should a built release only include the Webware/*/Docs/RelNotes-*.html, > and InstallGuide.html? and maybe Devloping? > > Leaving things like the UsersGuide, Future, Tutorial, > ApplicationDevelopment, etc.. to be on the web site, and optionally > downloaded seperately?
I would propose that only documentation tied to the release should be included in the release package. I would identify those documents as the release notes, the install guide, and any sort of reference guide. Oh, and some sort of About page -- after all, if we're going to link to the website, we need a page that does the linking (and links to the bug tracker, mailing list, etc). Right now more documentation is better -- so even if you are using 0.8 six months from now, I think the up-to-the-date documentation at that time will be better than the documentation we might release with 0.8. But that's not always true. Actually, now that I think about it, it has the potential to be very untrue -- like with ApplicationDevelopment I made a bunch of changes to MakeAppWorkDir that occurred to me as I wrote the documentation. For these things, though, I would be quite open to marking the document with version information, or at least mark stuff that's only available in the CVS version. That will be also be convenient when reviewing what's been changed since the last release. > By placing the documents on the web site, and providing more seperation > between the documentation and the product release process, are you > thinking of using revision dates on the documents to track versions? Or > perhaps the CVS revision information? We could branch the documentation at the same time as the release. We could also do an export to the website, and via some mechanism allow the user to view the document as it existed for that release. I'm willing to commit some server space to this too, if anyone has an interest in implementing any of this stuff in Webware. Depending on the bandwidth requirements the whole website could run on on my server, or maybe just portions... I'm not sure where we can find access logs...? It would be nice to allow commenting on the documentation, ala php.net (I've been coding some PHP lately, and while I still hate PHP and am unimpressed with the PHP documentation, the comments usually make up for any missing material in the documentation) > How are you thinking of managing them in CVS? I could see keeping the > docs in CVS with the project right now, and having a builddocs command > that would run buildhtml on them, collect them into a navigable tree, > and possibly publish them to a specified directory on the web site. Or > possibly having another top level Webware-docs CVS module, and moving > them out of the existing areas. (originally I think I wasn't too keen > on the seperate CVS module, but it has merrits.) > > Do you want to try tackling any of this with this release? No, this release is almost done. Whatever our longterm plans, we can certainly make the new documentation available to 0.8 users after the release. Let's just get this one out the door. We can also potentially do an 0.8.1 sometime with the added documentation. The only reason I'd really like the documentation with a release (in spirit if not in a single tarball) is so we can say "Webware: Now With Documentation!" in an announcement -- I think thorough documentation is a pretty important feature for which Webware is overdue. We could make an 0.8.1 which fixes any bugs we find in 0.8, plus backport the documentation (which should be easy). As I think about it more, though, we should also review the website for the 0.8 release. It's functional if not exciting. But when the announcements go out I think a lot of people with just a slight interest may look at the website, and we'd like to get them interested. Like I really like to see an example straight off. Other people will like a list of features. Others will like comparisons. Maybe we can provide all of those... there's a fair amount of material on the Wiki already (Oh, and the Wiki is another thing we can move to Webware if someone is interested). -- Ian Bicking Colorstudy Web Development [EMAIL PROTECTED] http://www.colorstudy.com PGP: gpg --keyserver pgp.mit.edu --recv-keys 0x9B9E28B7 4869 N Talman Ave, Chicago, IL 60625 / (773) 275-7241 ------------------------------------------------------- This SF.NET email is sponsored by: SourceForge Enterprise Edition + IBM + LinuxWorld = Something 2 See! http://www.vasoftware.com _______________________________________________ Webware-devel mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/webware-devel
