[
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.
