documentation

From: Aristedes Maniatis (ar..sh.com.au)
Date: Mon May 25 2009 - 20:11:54 EDT

  • Next message: Andrus Adamchik: "Re: documentation"

    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 May 25 2009 - 20:12:33 EDT