Mailing-List: contact dev-help@openjpa.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@openjpa.apache.org
Received-SPF: pass (nike.apache.org: domain of kwsutter@gmail.com designates
 209.85.219.219 as permitted sender)
DomainKey-Signature: a=rsa-sha1; c=nofws;
        d=gmail.com; s=gamma;
        h=mime-version:date:message-id:subject:from:to:content-type;
        b=DFz2TqP33MFj2RxYTPkX0rsNtckzIimki0gAeHDIvmis04TyDC5hye/u2ciVqwXik2
         gDkOIlHByMiXe2K0iOI++8pq+Pv6CRegMi+5jNSsxPtVsOtAP3bAlPZ18vFC1u2b0qKa
         xo4YxmgcRZ17xt9CqD/uHVLp5nHDjs/H4LWIg=
MIME-Version: 1.0
Date: Tue, 24 Nov 2009 09:16:01 -0600
Message-ID: <89c0c52c0911240716u5f5ef062jfa780953b3555188@mail.gmail.com>
Subject: JIRA references in documentation?
From: Kevin Sutter <kwsutter@gmail.com>
To: dev@openjpa.apache.org
Content-Type: multipart/alternative; boundary=000e0cdf6d0486cf3704791f6bbe

--000e0cdf6d0486cf3704791f6bbe
Content-Type: text/plain; charset=ISO-8859-1

Hi,
While I was looking for some information in our documentation in trunk, I
came across several references to JIRAs.  The section on Incompatibilities
[1] really stuck out for me.  I'm not thrilled with this approach.  For a
few reasons...

o  It forces customers to go find some other tool (JIRA) to look up
additional information.  We've found several Users and even some Dev mailing
list contributors that don't know anything about JIRA.

o  It makes us look "lazy".  Instead of completing the documentation, we're
telling customers to go on a scavenger hunt.

o  Some of the references are basically worthless.  For example, in the
section on detach [2], there is a reference to OPENJPA-1215 for more
testcases that document the situation.  But, there are no patches or commits
on this JIRA, so the reference is bogus.

Now that you know my thoughts on this approach, I'd like to hear your
comments and ideas.  If agreeable, then I'd also like to solicit volunteers
to get this cleaned up.

Thanks,
Kevin

[1]
http://openjpa.apache.org/builds/latest/docs/manual/manual.html#jpa_2.0_incompatibilities
[2]
http://openjpa.apache.org/builds/latest/docs/manual/manual.html#migration_detach_behavior

--000e0cdf6d0486cf3704791f6bbe--