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
> 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
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
Ian Bicking Colorstudy Web Development
PGP: gpg --keyserver pgp.mit.edu --recv-keys 0x9B9E28B7
4869 N Talman Ave, Chicago, IL 60625 / (773) 275-7241