search

jcp-org / import-issues-test

0 stars 0 forks source link

JSR348-91: State the document version explicitly in the Executive Summary #86

Closed apastsya closed 7 years ago

apastsya commented 13 years ago

Jira issue originally created by user pcurran:

From Alex Buckley.

On line 19 of the PR draft change "This version" to "Version 2.8"

apastsya commented 13 years ago

Comment created by eduardo:

I think that would be a mistake -- leaving it as is would save the user to have to go to the very top of the document to verify that they are indeed reading version 2.8; I'd rather not make this change

apastsya commented 13 years ago

Comment created by eduardo:

Please reopen this issue if you disagree with this disposition.

apastsya commented 13 years ago

Comment created by pcurran:

In the interests of full disclosure, this change was suggested by Alex Buckley. I asked him "Why? It reads just fine as it is." He responded:

"I believe in extreme clarity for narrative specs. The ultimate goal is being able to identify version-specific artifacts in a spec. Wikipedia gets it right:

http://en.wikipedia.org/wiki/Wikipedia:Manual*of_Style_%28words_to_watch%29#Relative_time*references http://en.wikipedia.org/wiki/Wikipedia:As_of

(One of the most valuable JVMS additions was documenting which class file content was introduced with which class file version. For the Process Doc, it would be nice to record which JSR introduced which Process. People will be grateful circa JCP 6.2 in 2024.)"

I guess we could say "This version (2.8)"

apastsya commented 13 years ago

Comment created by pcurran:

Reopeneing, since I suggested a compromise in an earlier comment.

apastsya commented 13 years ago

Comment created by eduardo:

I totally agree with Wikipedia on this, particularly as regards relative time references and lack of specificity, but the sentence in question is quite specific, as it identifies which JSR was used to produce this version. There is no need, in my view, to send the reader scrambling to verify that he/she is indeed reading version 2.8. In 2024 the reference will be to JSR 10456, and that will also be specific enough.

I still think it should not be changed, but I'm curious to know what others, particularly Alex, think about this.

apastsya commented 13 years ago

Comment created by eduardo:

I'm still waiting for any further comments on this

apastsya commented 13 years ago

Comment created by pcurran:

Looks good to me - please close this issue.

Thanks...

apastsya commented 13 years ago

Issue was closed with resolution "Won't Fix"