--- Phil Steitz <[EMAIL PROTECTED]> wrote: > All good points below. How about the following strategy: > > 1) Web site always reflects state of current development (essentially CVS > head). We get better at keeping it up to date (I have been lazy about > this), trying to update it after every significant change and at least > once a month.
-1 IIRC, Mark will argue against having the Web site reflect the current state of development, and I now would agree with him. The Web site should reflect the current official release version. Perhaps we could have an additional section of the site where the current development version is reflected nightly? > 2) With each release (yes, there really will be releases ;-), we tar > generated html with relative links including both javadocs and user guide. > Struts and tomcat at least used to do this (haven't grabbed distros of > either recently). That way users always have guide + javadoc matching > what they have deployed. This should not be a problem using maven. +1 > 3) We try to limit dependencies on external html links as much as > possible, favoring inline exposition in the javadoc or user guide when > this is feasible and dead tree references when what is needed is a > reference citation. The last sentence conflicts with what we have in the > developer's guide, so I guess I am proposing that we change this policy. > I am just afraid that if we include a lot of external links in the html > that we distribute with releases, we will have no way of keeping them up > to date. I am not proposing that we hold 1.0 until we get rid of them all > --just try to eliminate the less stable ones and do not continue to add more. I would prefer a stable hyperlink over a paper reference any day. Providing both would be acceptable, so that if the hyperlink has gone stale, there's still a concrete reference to look up. I for one would feel more confident doing a Web search when I found a reference link unreachable if I knew ultimately there was a paper reference to consult. Al > Phil > > > Mark R. Diggory wrote: > > Nightly update tends to be frowned upon because usually the site > > documentation is tied to a specific release. I think the Maven folks are > > working on a means to have older versions of docs archived so that they > > can be accessed. > > > > The issue is one of referential integrity. Say we release javadoc for > > version 1.0 and have user doc on the math site that it links to. Then > > (lets say) we update the doc on the site such that a page is removed. > > Now there are versions of the javadoc out in the wild that point to a > > dead link. So, linking in such a way is very restrictive to our being > > able to update the user guide. > > > > Now, I think the user guide is not that large that it couldn't be > > distributed on combination with the javadoc, then the javadoc references > > could be based on relative linking to the local copy of the userdoc. > > > > Ultimately we are trying to resolve the fact that we can't use xdoc in > > such a way as to embed it into javadoc directly. Would we even want to?! > > I think its best if we maintain a parallel xdoc structure to the javadoc > > package structure and distribute them together as one package that is > > relatively linked. This really just means packaging up portions of the > > site docs such that they are expanded from the tar file and that they > > can still be navigated in the local file system in a browser > > > > -Mark --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
