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.

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.

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.

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

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!

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!

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

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.

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.

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.

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.

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.

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