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
