The uncertainty about the spec documents possibly not transferring is worrying.
In many of them there’s key “documentation” about intended behaviour, so a key aspect would be lost if those were not transferred.
As I mentioned before, in case of JSF the spec document (the PDF) is not complete. Quite some things that otherwise perhaps could have been in the spec pdf was written in JavaDoc. So in JSF’s case it’s not so much about recreating the spec from the JavaDoc, but part of the JavaDoc already *is* the spec.
I understood that a major issue is that the spec documents are not simply GPL or Apache or Creative Commons, and that their IP flows and potential patents are quite different.
I for one would like to know what the
key EE4J stakeholders are thinking about this.
One key to success is having excellent documentation for Jakarta
EE - one in the form of a reference guide and another in the form
of quick getting started guides for common use cases. In terms of
existing Java EE, the Java EE Tutorial sort of served as the
former and we never really had an official solution for the latter
(though the FirstCup demo application helped a bit). Nonetheless,
the specification document was always the go-to when you really
needed to dig into the details, especially as a contributor,
implementer or early author. Is one solution to simply focus on
writing the reference guide and how-to material better and rely on
Javadoc for more fine grained details?
How do other successful open standards do this?
On 6/23/2018 1:09 PM, Josh Juneau wrote:
I would
like to address one of the transition points that hasn't yet
been worked out completely in the Oracle-to-Eclipse donation
process. This is the fact that the transfer of the Java EE
specification documents is in question at this time, as we know
that there are legal issues with transferring them directly to
Eclipse, as-is. I know that there are varying opinions in the
community as to whether the specification documents themselves
are really essential moving forward, but I want to voice my
opinion that they are a crucial part of the specification.
Sure, the JavaDoc can be used to implement variations of a
specification, but the concrete specification document should be
followed as a baseline for anyone wishing to implement the
specification, and without those documents being transferred,
as-is, lots of history will be lost.
I
know that one possible solution would be to have a working
group reproduce the specification documents for the individual
EE4J projects. In my opinion, this would be a nightmare as it
would be impossible to convey the wording contained in the
specification document without plagiarism coming into
question. If the wording (and ordering) of the documents were
to change radically, then the initial intentions conveyed
within the specifications may be lost. In short, the
specification documents cannot be reproduced.
Another
possible solution would be to create new specification
documents, which could point back to the original
documentation. This, in my opinion, may be a better solution.
However, it may become cumbersome to be redirected from a new
specification document back to the original...making the
documentation difficult to follow. If the documents cannot be
transferred outright, then maybe the new Jakarta EE Platform
specification documents can utilize the section headers from
the original specification documents as links to point back to
the original documentation. It would be great if the new
specifications can "quote" the original specification text,
but I am not sure if that is legally possible. If linking
back to the original text, then over time as sections of a
specification are re-written to accommodate spec changes or
new sections are added, the new specification documents would
be able to progress without losing the history of the original
specifications.
In
the end, my intention is to ensure that the specification
documents are not merely tossed aside as historical
documentation. They need to be incorporated, somehow, into
the new formal specification process moving forward. The best
solution would ultimately be to allow them to be transferred
as-is, but I know there are IP issues that likely make that
not legally possible. I know that those at Oracle and the
Eclipse will make the right decision and choose the best path
forward.
There
is a lot of great (difficult) work being done behind the
scenes at both the Oracle and Eclipse camps to make this
transition possible, and the community certainly appreciates
all of the efforts. The open platform is going to be a
great success, and I look forward to watching and helping
the Jakarta EE Platform evolve.
