documentation

[Aristedes Maniatis]

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 [phone]   fax [phone]
GPG fingerprint CBFB 84B4 738D 4E87 5E5C  5EFA EF6A 7D2E 3E49 102A

[Andrus Adamchik]

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 [phone]   fax [phone]
> GPG fingerprint CBFB 84B4 738D 4E87 5E5C  5EFA EF6A 7D2E 3E49 102A
>
>
>

[Andrus Adamchik]

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 [phone]   fax [phone]
>> GPG fingerprint CBFB 84B4 738D 4E87 5E5C  5EFA EF6A 7D2E 3E49 102A
>>
>>
>>
>
>

[Malcolm Edgar-2]

Also having bundled documentation is very useful when you are working
on sites where there in no internet connectivity, for example defense
sites.

regards Malcolm Edgar

On Mon, Jun 29, 2009 at 5:43 PM, Andrus Adamchik<[hidden email]> 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 [phone]   fax [phone]
>>> GPG fingerprint CBFB 84B4 738D 4E87 5E5C  5EFA EF6A 7D2E 3E49 102A
>>>
>>>
>>>
>>
>>
>
>

[Michael Gentry-2]

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<[hidden email]> 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 [phone]   fax [phone]
>>> GPG fingerprint CBFB 84B4 738D 4E87 5E5C  5EFA EF6A 7D2E 3E49 102A
>>>
>>>
>>>
>>
>>
>
>

[Kevin Menard-4]

I'm -0.  If they were gone, I'd get by.  But, I've had a habit of
copying the doc HTML to a local-to-me Web server so I could read off
that.  All the docs for the various projects at the versions I need
are right there, so I don't have to hunt them down on the Internet.
But, I'm less trustful than many.

--
Kevin



On Mon, May 25, 2009 at 8:11 PM, Aristedes Maniatis<[hidden email]> 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 [phone]   fax [phone]
> GPG fingerprint CBFB 84B4 738D 4E87 5E5C  5EFA EF6A 7D2E 3E49 102A
>
>
>