users@jersey.java.net

Re: Misc comments on docs

From: Paul Sandoz <Paul.Sandoz_at_Sun.COM>
Date: Mon, 27 Aug 2007 18:51:31 +0200

Hi Arun,

Arun Gupta wrote:
> I downloaded the latest 2.1 ea snapshot and have few comments:
>
> 1). The Getting Started at [1] is a much more concise version of the
> bundled getting-started.html. I mentioned this earlier as well, and here
> again, that getting-started.html is little too detailed for "getting
> started". This document is certainly relevant and has great content but
> I'd rather see [1] as the standard getting started and
> getting-started.html as the one with more details/explanation.
>
> If you still disagree, which is ok, then I'll not raise this topic again :)
>

Tis OK, i agree with you. In fact this document is out of date and needs
to be revised. I will replace the getting started with the one on the
jersey project (and move the original to something else).


> 2). The common convention for directory name for samples/examples is
> "samples". For example look at glassfish-samples, Metro, JAX-WS & JAXB.
> I propose to change the directory name from "examples" to "samples".
>
> Even getting-started.html heading (at the bottom of the page) says Samples.
>

I renamed 'samples' to 'examples' for the Jersey release. The reasoning
was i thought 'samples' sounded too medical or chemical, for example
'here you can find a sample of using atom', i prefer 'here you can find
an example of using atom'.

However, i will rename it back for consistency with other GF-based projects.


> 3). IMHO, Samples section from getting-started.html should move as a new
> file to the samples directory and then linked from there.

Good point. We need to have some automated index page generated.


> Moreover there
> are 10 samples and only 7 are linked from the page.
>

I know :-) it is on the work to do list.

Paul.

-- 
| ? + ? = To question
----------------\
    Paul Sandoz
         x38109
+33-4-76188109