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:
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
>>
>>
>>
>
>
This archive was generated by hypermail 2.0.0 : Mon Jun 29 2009 - 03:44:35 EDT