Details

    • Type: Sub-task Sub-task
    • Status: Closed
    • Priority: Minor Minor
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 10.6.1.0
    • Component/s: Documentation
    • Labels:
      None

      Description

      This sub-task of DERBY-2487 is for tracking the documentation of the new feature. I think
      it will be a little bit simpler to track the documentation changes in a separate issue.

      1. ctun_xplain_mode.html
        8 kB
        Bryan Pendleton
      2. ctun_xplain_mode.html
        7 kB
        Bryan Pendleton
      3. ctun_xplain_tables.html
        6 kB
        Bryan Pendleton
      4. earlyDraftDocs.diff
        77 kB
        Bryan Pendleton
      5. earlyDraftDocs.diff
        75 kB
        Bryan Pendleton
      6. earlyDraftDocs.diff
        71 kB
        Bryan Pendleton
      7. earlyDraftDocs.diff
        60 kB
        Bryan Pendleton
      8. rrefresetxplaintablesproc.html
        3 kB
        Bryan Pendleton
      9. rrefsetxplainmodeproc.html
        4 kB
        Bryan Pendleton
      10. rrefsetxplainstyleproc.html
        3 kB
        Bryan Pendleton
      11. rrefsyscsgetxplainmode.html
        3 kB
        Bryan Pendleton
      12. rrefsyscsgetxplainstyle.html
        3 kB
        Bryan Pendleton
      13. rrefsysxplain_resultset_timings.html
        11 kB
        Bryan Pendleton
      14. rrefsysxplain_resultsets.html
        17 kB
        Bryan Pendleton
      15. rrefsysxplain_resultsets.html
        15 kB
        Bryan Pendleton
      16. rrefsysxplain_scan_props.html
        13 kB
        Bryan Pendleton
      17. rrefsysxplain_scan_props.html
        13 kB
        Bryan Pendleton
      18. rrefsysxplain_sort_props.html
        9 kB
        Bryan Pendleton
      19. rrefsysxplain_statement_timings.html
        10 kB
        Bryan Pendleton
      20. rrefsysxplain_statements.html
        11 kB
        Bryan Pendleton
      21. rrefsysxplain_statements.html
        10 kB
        Bryan Pendleton
      22. userSchema.diff
        82 kB
        Bryan Pendleton

        Activity

        Hide
        Bryan Pendleton added a comment -

        The docs are visible on the web site, marking issue resolved.

        Show
        Bryan Pendleton added a comment - The docs are visible on the web site, marking issue resolved.
        Hide
        Bryan Pendleton added a comment -

        SVN revision 773758 backs out the cross-manual XREF tags. These tags appeared to
        work properly in the HTML pages format, but in fact they were not correct there (they
        mishandled the TOC) and moreover the tags were not working at all in the PDF and
        HTML single-page format.

        Show
        Bryan Pendleton added a comment - SVN revision 773758 backs out the cross-manual XREF tags. These tags appeared to work properly in the HTML pages format, but in fact they were not correct there (they mishandled the TOC) and moreover the tags were not working at all in the PDF and HTML single-page format.
        Hide
        Bryan Pendleton added a comment -

        Thanks Kim and Dag for the reviews and assistance.

        I think I've addressed the comments and suggestions, and have committed
        the documentation to the docs trunk as revision 773294.

        I'll leave this issue open until I can verify that the docs are visible on the web site,
        then I'll resolve this issue.

        I'm sure there will be changes needed to the docs once people have a chance
        to work with the new feature, but we can address those as separate JIRA issues.

        Show
        Bryan Pendleton added a comment - Thanks Kim and Dag for the reviews and assistance. I think I've addressed the comments and suggestions, and have committed the documentation to the docs trunk as revision 773294. I'll leave this issue open until I can verify that the docs are visible on the web site, then I'll resolve this issue. I'm sure there will be changes needed to the docs once people have a chance to work with the new feature, but we can address those as separate JIRA issues.
        Hide
        Bryan Pendleton added a comment -

        Thanks Kim! This is extremely helpful. I'll try to address these issues, then hopefully commit
        this work within a week or so. Some of the FIXMEs will take longer to address, but I'll move
        them out of the docs themselves and into the issue tracking system where they can be
        tracked and resolved.

        Show
        Bryan Pendleton added a comment - Thanks Kim! This is extremely helpful. I'll try to address these issues, then hopefully commit this work within a week or so. Some of the FIXMEs will take longer to address, but I'll move them out of the docs themselves and into the issue tracking system where they can be tracked and resolved.
        Hide
        Kim Haase added a comment -

        Sorry for the delay, Bryan!

        These are really good – I am not the technical expert, but the topics are very well written and clear. There are only a few fixes that seem significant – some should be done before you commit, some can wait.

        src/tuning/tuningderby.ditamap:
        I think you may not have done an svn update before editing this file, because it reverts to the 10.4 version and 2008 date. (The Reference Manual map file doesn't have this problem.) The patch command fails on the non-updated part.

        src/tuning/ctun_xplain_tables.dita:
        In the concept element, the id value should be

        <concept xml:lang="en-us" id="ctun_xplain_tables">

        instead of

        <concept xml:lang="en-us" id="ctun_xplain_tables.dita">

        (This is the convention observed in all the files to make xrefs work. I notice that the new topics in the Reference Manual use the correct convention for their id values.)

        src/tuning/ctun_xplain_style.dita:
        Same id issue as with ctun_xplain_tables.dita.

        Also, in this topic you might want to point people to the Reference Manual for info about the tables and system functions/procedures.

        Similarly, in the Reference Manual you might want to add some cross-references. From the procedure/function topics and the main tables topic, you could point to the Tuning Guide information on how to use xplain mode. Also, the topics on the functions and procedures could point to the main topic on the tables. The references in the table topics could be improved: some of them contain a general mention of the "RUNTIMESTATISTICS section" of the reference manual; if this section is really in the reference manual you could refer to the exact topic, but I suspect the "Working with RunTimeStatistics" section of the tuning guide might be what's intended.

        An actual error, I think: in rref_syscs_set_xplain_schema.dita, there's a reference to SYSCS_UTIL.SYSCS_SET_XPLAIN_STYLE, whose name has changed.

        The syntax statement for SYSCS_UTIL.SYSCS_GET_XPLAIN_MODE doesn't say what the function returns, as the syntax for SYSCS_UTIL.SYSCS_GET_XPLAIN_SCHEMA does. Should it? (Is it an INTEGER or a SMALLINT?)

        Some of the table topics have "FIXME" and some queries in the descriptions, so I hope you get those questions answered. These topics also have "Derby" hard-coded instead of <ph conref="../conrefs.dita#prod/productshortname"></ph>, but I imagine you are waiting for the text to solidify before you make that fix.

        Show
        Kim Haase added a comment - Sorry for the delay, Bryan! These are really good – I am not the technical expert, but the topics are very well written and clear. There are only a few fixes that seem significant – some should be done before you commit, some can wait. src/tuning/tuningderby.ditamap: I think you may not have done an svn update before editing this file, because it reverts to the 10.4 version and 2008 date. (The Reference Manual map file doesn't have this problem.) The patch command fails on the non-updated part. src/tuning/ctun_xplain_tables.dita: In the concept element, the id value should be <concept xml:lang="en-us" id="ctun_xplain_tables"> instead of <concept xml:lang="en-us" id="ctun_xplain_tables.dita"> (This is the convention observed in all the files to make xrefs work. I notice that the new topics in the Reference Manual use the correct convention for their id values.) src/tuning/ctun_xplain_style.dita: Same id issue as with ctun_xplain_tables.dita. Also, in this topic you might want to point people to the Reference Manual for info about the tables and system functions/procedures. Similarly, in the Reference Manual you might want to add some cross-references. From the procedure/function topics and the main tables topic, you could point to the Tuning Guide information on how to use xplain mode. Also, the topics on the functions and procedures could point to the main topic on the tables. The references in the table topics could be improved: some of them contain a general mention of the "RUNTIMESTATISTICS section" of the reference manual; if this section is really in the reference manual you could refer to the exact topic, but I suspect the "Working with RunTimeStatistics" section of the tuning guide might be what's intended. An actual error, I think: in rref_syscs_set_xplain_schema.dita, there's a reference to SYSCS_UTIL.SYSCS_SET_XPLAIN_STYLE, whose name has changed. The syntax statement for SYSCS_UTIL.SYSCS_GET_XPLAIN_MODE doesn't say what the function returns, as the syntax for SYSCS_UTIL.SYSCS_GET_XPLAIN_SCHEMA does. Should it? (Is it an INTEGER or a SMALLINT?) Some of the table topics have "FIXME" and some queries in the descriptions, so I hope you get those questions answered. These topics also have "Derby" hard-coded instead of <ph conref="../conrefs.dita#prod/productshortname"></ph>, but I imagine you are waiting for the text to solidify before you make that fix.
        Hide
        Bryan Pendleton added a comment -

        Attached 'userSchema.diff' is a revised patch proposal for the documentation.

        The changes are fairly minor compared to the previous patch proposals,
        and mostly involve:

        • adjustments to describe that the captured statistics information is now
          stored in ordinary database tables in a user-specified schema, rather than
          in system catalogs.
        • adjustments to reflect the system procedure changes: SYSCS_RESET_XPLAIN_TABLES
          no longer exists, and SYSCS_[GET,SET]_XPLAIN_STYLE has been renamed
          to SYSCS_[GET,SET]_XPLAIN_SCHEMA
        • re-arrangement of the table documentation for the XPLAIN tables into its
          own section of the reference manual
        • re-naming of the underlying DITA file names to make things easier on
          my poor eyes and try to follow a more consistent naming convention.

        It will take a while to make this documentation polished, and I think that we can do
        a lot of that work in subsequent changes.

        What I'd like to do at this point is address any major issues with the documentation
        that need to be fixed prior to its initial commit into the docs trunk, then get the
        initial version of the docs committed, and then incrementally improve the docs.

        If anybody has time to review 'userSchema.diff', that would be much appreciated.

        Show
        Bryan Pendleton added a comment - Attached 'userSchema.diff' is a revised patch proposal for the documentation. The changes are fairly minor compared to the previous patch proposals, and mostly involve: adjustments to describe that the captured statistics information is now stored in ordinary database tables in a user-specified schema, rather than in system catalogs. adjustments to reflect the system procedure changes: SYSCS_RESET_XPLAIN_TABLES no longer exists, and SYSCS_ [GET,SET] _XPLAIN_STYLE has been renamed to SYSCS_ [GET,SET] _XPLAIN_SCHEMA re-arrangement of the table documentation for the XPLAIN tables into its own section of the reference manual re-naming of the underlying DITA file names to make things easier on my poor eyes and try to follow a more consistent naming convention. It will take a while to make this documentation polished, and I think that we can do a lot of that work in subsequent changes. What I'd like to do at this point is address any major issues with the documentation that need to be fixed prior to its initial commit into the docs trunk, then get the initial version of the docs committed, and then incrementally improve the docs. If anybody has time to review 'userSchema.diff', that would be much appreciated.
        Hide
        Dag H. Wanvik added a comment -

        I did a quick scan of the docs and they are very readable. Thanks for this Bryan!

        Show
        Dag H. Wanvik added a comment - I did a quick scan of the docs and they are very readable. Thanks for this Bryan!
        Hide
        Kim Haase added a comment -

        Thanks for the suggestion, Bryan. I've noticed just a few minor things:

        You can use the definitions in the conrefs.dita file for references to other books: <ph conref="../conrefs.dita#pub/cittuning"></ph> or <ph conref="../conrefs.dita#pub/citref"></ph>.

        Great explanation of XPLAIN vs. explain – though you might want to reword it to take out the uses of "we", which is a bit informal for tech writing. ("You" is totally acceptable, of course.) Also, you might add an explanation of the difference between xplain style and xplain mode.

        When you change a topic title, make sure to update the map file entry too (just for consistency – I don't think the map file title is used anywhere).

        I think the rrefsyscsgetxplainstyle topic has a typo where it uses "explain" instead of "xplain" in the second paragraph.

        The two system function topics should have examples (even if they are a bit lame) to be consistent with the other system function topics.

        The other system procedure topics include both a JDBC example and an SQL example – you might consider providing both. Also, the example code is usually left-aligned rather than indented.

        Some topics use the term "xplain_style" while others use "XPLAIN style" – it would be good to be consistent. (Also with "mode" in one case, I think.)

        Put the system function and procedure names in all caps when you use them in text, and if the example is one of usage rather than just the name of the table, put it in code font (see refsysxplain_statement_timings.html). I think that's the only instance that needs fixing.

        The tables in the system table topics all look great. I assume you will be adding data in the FIXME table cells. You could also make the references to system procedures and other tables into cross-references to the topics for those items.

        There's an odd reference to a dita file in rrefsysxplain_resultset_timings.dita; I'm guessing that a reference to another system procedure was intended.

        That's all. Your writing is excellent!

        Show
        Kim Haase added a comment - Thanks for the suggestion, Bryan. I've noticed just a few minor things: You can use the definitions in the conrefs.dita file for references to other books: <ph conref="../conrefs.dita#pub/cittuning"></ph> or <ph conref="../conrefs.dita#pub/citref"></ph>. Great explanation of XPLAIN vs. explain – though you might want to reword it to take out the uses of "we", which is a bit informal for tech writing. ("You" is totally acceptable, of course.) Also, you might add an explanation of the difference between xplain style and xplain mode. When you change a topic title, make sure to update the map file entry too (just for consistency – I don't think the map file title is used anywhere). I think the rrefsyscsgetxplainstyle topic has a typo where it uses "explain" instead of "xplain" in the second paragraph. The two system function topics should have examples (even if they are a bit lame) to be consistent with the other system function topics. The other system procedure topics include both a JDBC example and an SQL example – you might consider providing both. Also, the example code is usually left-aligned rather than indented. Some topics use the term "xplain_style" while others use "XPLAIN style" – it would be good to be consistent. (Also with "mode" in one case, I think.) Put the system function and procedure names in all caps when you use them in text, and if the example is one of usage rather than just the name of the table, put it in code font (see refsysxplain_statement_timings.html). I think that's the only instance that needs fixing. The tables in the system table topics all look great. I assume you will be adding data in the FIXME table cells. You could also make the references to system procedures and other tables into cross-references to the topics for those items. There's an odd reference to a dita file in rrefsysxplain_resultset_timings.dita; I'm guessing that a reference to another system procedure was intended. That's all. Your writing is excellent!
        Hide
        Bryan Pendleton added a comment -

        Hi Kim, thanks for having a look at the patch. I think that's a good suggestion,
        and I've uploaded a new version of ctun_xplain_mode.html with some
        additional content, as well as a revised copy of the entire patch.

        You are correct that this work is still fairly volatile, but it would be
        great to have whatever feedback you think you can provide as early
        as you can provide it. You may not want to go through it line-by-line
        at this point, but if you can notice some common mistakes that I'm
        making repeatedly throughout the content, then it would be great to
        catch those and I can start cleaning them up.

        So whatever observations or suggestions you can make would be
        most appreciated!

        Show
        Bryan Pendleton added a comment - Hi Kim, thanks for having a look at the patch. I think that's a good suggestion, and I've uploaded a new version of ctun_xplain_mode.html with some additional content, as well as a revised copy of the entire patch. You are correct that this work is still fairly volatile, but it would be great to have whatever feedback you think you can provide as early as you can provide it. You may not want to go through it line-by-line at this point, but if you can notice some common mistakes that I'm making repeatedly throughout the content, then it would be great to catch those and I can start cleaning them up. So whatever observations or suggestions you can make would be most appreciated!
        Hide
        Kim Haase added a comment -

        The docs look great, Bryan – the topics and organization make perfect sense. I won't offer any detail nits till you are past the rough-draft stage. It looks as if some implementation details may still be in flux.

        It might be helpful, in the introductory conceptual topic in the Tuning Guide, to mention why the feature is called XPLAIN instead of EXPLAIN – there should be a way to summarize Felix's explanation from DERBY-2487 briefly. It's a question users are likely to ask. (You did, I think!)

        Show
        Kim Haase added a comment - The docs look great, Bryan – the topics and organization make perfect sense. I won't offer any detail nits till you are past the rough-draft stage. It looks as if some implementation details may still be in flux. It might be helpful, in the introductory conceptual topic in the Tuning Guide, to mention why the feature is called XPLAIN instead of EXPLAIN – there should be a way to summarize Felix's explanation from DERBY-2487 briefly. It's a question users are likely to ask. (You did, I think!)
        Hide
        Bryan Pendleton added a comment -

        Attaching an updated copy of the docs draft patch, as well as updated HTML for
        the 3 pages that are modified, namely the reference pages for the
        resultsets, scan_props, and statements tables.

        Show
        Bryan Pendleton added a comment - Attaching an updated copy of the docs draft patch, as well as updated HTML for the 3 pages that are modified, namely the reference pages for the resultsets, scan_props, and statements tables.
        Hide
        Bryan Pendleton added a comment -

        Attaching an updated version of the diff patch, as well as HTML versions
        of the various pages I've been writing. There are two pages for the Tuning
        guide, and 11 pages for the reference guide.

        Comments on any or all of the pages are most welcome.

        Show
        Bryan Pendleton added a comment - Attaching an updated version of the diff patch, as well as HTML versions of the various pages I've been writing. There are two pages for the Tuning guide, and 11 pages for the reference guide. Comments on any or all of the pages are most welcome.
        Hide
        Bryan Pendleton added a comment -

        Attaching a very early, partial, incomplete docs patch which contains
        some draft documentation that I've been working on.

        The docs are nowhere near ready for commit, but I've done
        enough work that I thought it would be useful to post this work,
        so that people interested in the doc can give me some feedback
        about whether this is a reasonable approach to take for
        documenting this feature.

        Show
        Bryan Pendleton added a comment - Attaching a very early, partial, incomplete docs patch which contains some draft documentation that I've been working on. The docs are nowhere near ready for commit, but I've done enough work that I thought it would be useful to post this work, so that people interested in the doc can give me some feedback about whether this is a reasonable approach to take for documenting this feature.

          People

          • Assignee:
            Bryan Pendleton
            Reporter:
            Bryan Pendleton
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development