db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Kim Haase (JIRA)" <j...@apache.org>
Subject [jira] Commented: (DERBY-4065) Provide documentation for XPLAIN style statistics processing
Date Tue, 24 Feb 2009 15:42:05 GMT

    [ https://issues.apache.org/jira/browse/DERBY-4065?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12676315#action_12676315

Kim Haase commented on DERBY-4065:

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!

> Provide documentation for XPLAIN style statistics processing
> ------------------------------------------------------------
>                 Key: DERBY-4065
>                 URL: https://issues.apache.org/jira/browse/DERBY-4065
>             Project: Derby
>          Issue Type: Sub-task
>          Components: Documentation
>            Reporter: Bryan Pendleton
>            Assignee: Bryan Pendleton
>            Priority: Minor
>         Attachments: ctun_xplain_mode.html, ctun_xplain_mode.html, ctun_xplain_tables.html,
earlyDraftDocs.diff, earlyDraftDocs.diff, earlyDraftDocs.diff, earlyDraftDocs.diff, rrefresetxplaintablesproc.html,
rrefsetxplainmodeproc.html, rrefsetxplainstyleproc.html, rrefsyscsgetxplainmode.html, rrefsyscsgetxplainstyle.html,
rrefsysxplain_resultset_timings.html, rrefsysxplain_resultsets.html, rrefsysxplain_resultsets.html,
rrefsysxplain_scan_props.html, rrefsysxplain_scan_props.html, rrefsysxplain_sort_props.html,
rrefsysxplain_statement_timings.html, rrefsysxplain_statements.html, rrefsysxplain_statements.html
> 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.

This message is automatically generated by JIRA.
You can reply to this email to add a comment to the issue online.

View raw message