Derby
  1. Derby
  2. DERBY-5464

Add easier to find links to Derby JavaDoc on the Derby web site

    Details

    • Type: Task Task
    • Status: Closed
    • Priority: Minor Minor
    • Resolution: Fixed
    • Affects Version/s: 10.9.1.0
    • Fix Version/s: 10.9.1.0
    • Component/s: Web Site
    • Labels:
      None

      Description

      Add links to the Derby JavaDocs, which we do publish on the Derby web site.
      They can currently be found under Resources -> Papers -> Engine -> JavaDoc, but I'm proposing we add links to them under Documentation.

      1. derby-5464-1b-javadoc_links.diff
        6 kB
        Kristian Waagan
      2. derby-5464-1c-javadoc_links.diff
        6 kB
        Kristian Waagan
      3. derby-5464-javadoc_links.diff
        6 kB
        Kristian Waagan
      4. index-1a.html
        50 kB
        Kristian Waagan

        Issue Links

          Activity

          Hide
          Kristian Waagan added a comment -

          Attaching patch 1a, and the resulting HTML page (it looks odd due to the missing graphics etc, but the content can be seen).

          Patch ready for review.

          Show
          Kristian Waagan added a comment - Attaching patch 1a, and the resulting HTML page (it looks odd due to the missing graphics etc, but the content can be seen). Patch ready for review.
          Hide
          Kim Haase added a comment -

          Thanks, Kristian, the Javadoc links are a very good thing to have on the Documentation page. I am a bit puzzled, though, because in the draft page the links go to

          Engine – http://db.apache.org/derby/javadoc/engine/
          Language – http://db.apache.org/derby/javadoc/language/
          Testing – http://db.apache.org/derby/javadoc/testing/
          Tools – http://db.apache.org/derby/javadoc/tools/

          but not to the public API that would be of most use (I think?) to readers of the documentation. Whereas on the Apache Derby Papers page (http://db.apache.org/derby/papers/index.html), the links are to

          Engine (same)
          Language (same)
          Tools (same)
          API – http://db.apache.org/derby/javadoc/publishedapi/

          I wonder why the Testing API is not on the Papers site. Maybe it's in some other hard-to-find location?

          Perhaps all 5 should be linked to from both Papers and Documentation? Although arguably the published API is not strictly speaking internal, so maybe the title should just be

          Derby API Documentation

          Technically, "Javadoc" (initial capital only) is (or was) a trademarked term and has to be used as an adjective – Sun only allowed it to be used in front of "tool" or some such word, as I recall – so we generally say "API documentation" instead. I wouldn't worry about leaving "Javadoc" on the Papers page, though.

          Show
          Kim Haase added a comment - Thanks, Kristian, the Javadoc links are a very good thing to have on the Documentation page. I am a bit puzzled, though, because in the draft page the links go to Engine – http://db.apache.org/derby/javadoc/engine/ Language – http://db.apache.org/derby/javadoc/language/ Testing – http://db.apache.org/derby/javadoc/testing/ Tools – http://db.apache.org/derby/javadoc/tools/ but not to the public API that would be of most use (I think?) to readers of the documentation. Whereas on the Apache Derby Papers page ( http://db.apache.org/derby/papers/index.html ), the links are to Engine (same) Language (same) Tools (same) API – http://db.apache.org/derby/javadoc/publishedapi/ I wonder why the Testing API is not on the Papers site. Maybe it's in some other hard-to-find location? Perhaps all 5 should be linked to from both Papers and Documentation? Although arguably the published API is not strictly speaking internal, so maybe the title should just be Derby API Documentation Technically, "Javadoc" (initial capital only) is (or was) a trademarked term and has to be used as an adjective – Sun only allowed it to be used in front of "tool" or some such word, as I recall – so we generally say "API documentation" instead. I wouldn't worry about leaving "Javadoc" on the Papers page, though.
          Hide
          Kristian Waagan added a comment -

          Thanks, Kim.

          I'll address the trademark issue in the next revision of the patch, which will also include other required changes.

          Regarding the links to the different parts of the API documentation:
          o The public API is already linked to for each version of Derby on the documentation page.
          o The Apache Derby Papers page probably doesn't include testing because it's all about the engine (I'm just guessing here). Not sure if Tools fits into that theory though...

          Regarding the documentation page, we can (a) use "API documentation" and duplicate the link to the published API, or (b) use "Internal API documentation" with the engine, language, testing, and tools links.
          I lean towards (b) - i.e. a kind of Derby user vs Derby developer distinction [1] - but can happily go with (a) too

          Of course, the content can be organized in a totally different way too. For instance, we could add the links into the latest alpha docs table. My reason for not doing that, is that I doubt these links will be used much by Derby users.

          [1] Tools may not fit here, but then again BNF isn't the most user friendly documentation in my opinion... At least this one has comments and some helpful text

          Show
          Kristian Waagan added a comment - Thanks, Kim. I'll address the trademark issue in the next revision of the patch, which will also include other required changes. Regarding the links to the different parts of the API documentation: o The public API is already linked to for each version of Derby on the documentation page. o The Apache Derby Papers page probably doesn't include testing because it's all about the engine (I'm just guessing here). Not sure if Tools fits into that theory though... Regarding the documentation page, we can (a) use "API documentation" and duplicate the link to the published API, or (b) use "Internal API documentation" with the engine, language, testing, and tools links. I lean towards (b) - i.e. a kind of Derby user vs Derby developer distinction [1] - but can happily go with (a) too Of course, the content can be organized in a totally different way too. For instance, we could add the links into the latest alpha docs table. My reason for not doing that, is that I doubt these links will be used much by Derby users. [1] Tools may not fit here, but then again BNF isn't the most user friendly documentation in my opinion... At least this one has comments and some helpful text
          Hide
          Kim Haase added a comment -

          Silly me, I managed to miss those HTML links at the top of the docs for every release. Sorry, and thanks for pointing them out.

          You are right, (b) is the best bet, with the "Internal API documentation" section at the end, since it will be less often used.

          Show
          Kim Haase added a comment - Silly me, I managed to miss those HTML links at the top of the docs for every release. Sorry, and thanks for pointing them out. You are right, (b) is the best bet, with the "Internal API documentation" section at the end, since it will be less often used.
          Hide
          Kristian Waagan added a comment -

          Attaching patch 1b.

          Feel free to improve the language.

          Show
          Kristian Waagan added a comment - Attaching patch 1b. Feel free to improve the language.
          Hide
          Kim Haase added a comment -

          The language looks fine to me. You might change "described as BNF" to "described in BNF", I think. And if I were really inclined to quibble, I would suggest changing "only useful for" to "useful only for", but this is not necessary.

          Show
          Kim Haase added a comment - The language looks fine to me. You might change "described as BNF" to "described in BNF", I think. And if I were really inclined to quibble, I would suggest changing "only useful for" to "useful only for", but this is not necessary.
          Hide
          Kristian Waagan added a comment -

          Thank you, Kim.

          I have made the changes you proposed, and I committed patch 1c (attached) to trunk with revision 1186707.

          Show
          Kristian Waagan added a comment - Thank you, Kim. I have made the changes you proposed, and I committed patch 1c (attached) to trunk with revision 1186707.
          Hide
          Kristian Waagan added a comment -

          Updated the staging area on ppl. Will close the issue when they go live.

          Show
          Kristian Waagan added a comment - Updated the staging area on ppl. Will close the issue when they go live.
          Hide
          Kristian Waagan added a comment -

          Changes are live, closing issue.

          Show
          Kristian Waagan added a comment - Changes are live, closing issue.

            People

            • Assignee:
              Kristian Waagan
              Reporter:
              Kristian Waagan
            • Votes:
              0 Vote for this issue
              Watchers:
              0 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development