Tossing out a downside ... A lot of projects just commit the JARs, not the full download. So if someone checks out a local project from CVS/SVN/etc and only gets the JARs, the first place they'd probably look for documentation is the web site for the corresponding JAR.
mrg On Mon, Jun 29, 2009 at 3:43 AM, Andrus Adamchik<[email protected]> wrote: > Just stumbled on a reason to keep the docs together with the corresponding > release. > > I am using pretty old Tapestry 4.0 (cause Tapestry doesn't have a simple > upgrade path, but that's beyond the point). Tapestry comes with no bundled > docs, so the only way was to get them is via the web site: > > http://tapestry.apache.org/ > > Today I noticed that they delisted 4.0. Turns out the docs are still there > (if you know the URL : http://tapestry.apache.org/tapestry4/), good for > me... But this brings up an issue with keeping the old documentation on the > web site forever, which is bad for many reasons (such as Google > cross-version confusion). > > Having bundled docs frees us to modify the site any way we want. So I am > changing my vote here to -1. > > Andrus > > > > On May 26, 2009, at 10:52 AM, Andrus Adamchik wrote: > >> I am +0 on that. >> >> As long as we maintain separate doc branches on the site for the *major* >> releases, changes in the docs between the minor versions can be reasonably >> reflected in a single set of docs. Essentially, only the alpha release users >> will be affected, and they already have to deal with lagging docs anyways. >> >> Andrus >> >> >> On May 26, 2009, at 3:11 AM, Aristedes Maniatis wrote: >>> >>> The Cayenne project has long had bundled documentation within the release >>> itself. A maven script pulls the docs from Confluence and bundles them up. >>> I've long had a script which 95% works to do this from the final website >>> docs (so they look prettier), but I've never finished that last 5% which is >>> a bit fiddly and ties into bits of maven I don't understand. >>> >>> Given that there are likely to be changes to the way our website is built >>> which will invalidate the existing maven script and mine, I'd like to ask >>> whether we could save ourselves a whole lot of work and not bundle any docs >>> at all with the distribution. >>> >>> Advantages of removing docs from distribution >>> * smaller distribution >>> * less work to rework scripts and for the ongoing task of committing docs >>> to svn >>> * documentation is not frozen in time and fixed for errors or improved >>> clarity (for example users of 3.0M5 aren't seeing the new cache docs Andrus >>> wrote) >>> * nicer to look at >>> * ties in better with external resources (Jira, links to other sites, >>> etc) >>> >>> Advantages of keeping in distribution >>> * snapshot of documentation frozen in time as at that particular release >>> (which is a problem if we rewrite docs for new features and don't keep >>> historic doc pages) >>> * problem for people at 30,000 feet wanting to read docs (that and >>> somewhere in the Sahara desert where there is no internet access) >>> >>> >>> Many projects don't bundle all the docs with the download. Could we >>> create a set of a dozen introductory pages which point you to the >>> javadocs/website/etc? >>> >>> I'm +1 on the idea of removing them before 3.0 final. >>> >>> >>> Ari Maniatis >>> >>> >>> >>> --------------------------> >>> ish >>> http://www.ish.com.au >>> Level 1, 30 Wilson Street Newtown 2042 Australia >>> phone +61 2 9550 5001 fax +61 2 9550 4001 >>> GPG fingerprint CBFB 84B4 738D 4E87 5E5C 5EFA EF6A 7D2E 3E49 102A >>> >>> >>> >> >> > >
