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<andru..bjectstyle.org> 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
>>>
>>>
>>>
>>
>>
>
>
This archive was generated by hypermail 2.0.0 : Mon Jun 29 2009 - 09:17:54 EDT