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 : Tue May 26 2009 - 03:53:18 EDT