Re: documentation

[Kevin Menard <ni...@gmail.com>]

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<ar...@ish.com.au> 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
>
>
>