jsr348
  1. jsr348
  2. JSR348-91

State the document version explicitly in the Executive Summary

    Details

    • Type: Bug Bug
    • Status: Closed
    • Priority: Trivial Trivial
    • Resolution: Won't Fix
    • Component/s: Process Doc
    • Labels:
      None

      Description

      From Alex Buckley.

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

        Activity

        Hide
        eduardo added a comment -

        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

        Show
        eduardo added a comment - 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
        Hide
        eduardo added a comment -

        Please reopen this issue if you disagree with this disposition.

        Show
        eduardo added a comment - Please reopen this issue if you disagree with this disposition.
        Hide
        pcurran added a comment -

        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)"

        Show
        pcurran added a comment - 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)"
        Hide
        pcurran added a comment -

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

        Show
        pcurran added a comment - Reopeneing, since I suggested a compromise in an earlier comment.
        Hide
        eduardo added a comment -

        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.

        Show
        eduardo added a comment - 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.
        Hide
        eduardo added a comment -

        I'm still waiting for any further comments on this

        Show
        eduardo added a comment - I'm still waiting for any further comments on this
        Hide
        pcurran added a comment -

        Looks good to me - please close this issue.

        Thanks...

        Show
        pcurran added a comment - Looks good to me - please close this issue. Thanks...

          People

          • Assignee:
            eduardo
            Reporter:
            pcurran
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved: