[
https://issues.apache.org/jira/browse/DERBY-3072?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12528810
]
Kim Haase commented on DERBY-3072:
----------------------------------
This is great work, Rick -- you've structured the new topics very well, and
they are clear and well written. The tuning topics are amazingly clear for such
complex material. Here are some suggestions for improvement. Any topic with no
comments is just fine.
Global nit: According to the rules about restrictive and nonrestrictive clauses
as I learned them, "which" should be "that" in every location where it is used
in these topics. (Briefly, if the sentence would be meaningless without the
clause, use "that"; if the clause adds nonessential information, use "which"
and set it off with commas.)
Tuning Guide comments:
I think you may need to change one more file, the parent file of the new
performance tips file. The parent file is "The tips," ctunperf25864.dita. It
contains a manually created list of subtopics, with additional verbiage, in
addition to the autogenerated list at the bottom. So you'd need to add your new
topic there.
ctunperftablefunctions.html:
I'm wondering about "to cost" as a verb, from the point of view of translation.
Maybe "how to cost a ..." could be "how to calculate the cost of a ..." You
could also make the index terms similar to the ones for
cdevspecialtfopttune.dita.
I think we try to talk about topics rather than sections, but to avoid the
whole issue you could just say
See "Programming Derby-style table functions" in the Derby Developer's Guide.
Developer's Guide comments:
cdevspecialtabfuncs.html:
Paragraph 1: In the second sentence, "These" lacks a referent; when you are
introducing a topic it helps to be crystal clear. (This rule doesn't matter
much, since the meaning is clear regardless; it's just an FYI.) In the third
sentence, "xml" should be "XML". So I'd suggest the following:
Derby lets you create table functions. Table functions are functions that
package up external data to look like Derby tables. The external data can be an
XML file, a table in a foreign database, a live data feed--in short, any
information source that can be presented as a JDBC ResultSet.
Paragraph 2: It seems awkward to have a clause in between "the following data
sources" and the list of the data sources. It might be clearer to swap them and
use a sub-bullet list, like this:
For example, Derby-style table functions let you do the following:
* Perform a bulk import of foreign data into local Derby tables
* Join Derby tables with any of the following data sources:
* XML-formatted reports and logs
* Queries that have been run in foreign databases
* Streaming data from sensors
* RSS feeds
(I don't know that "bulk import" is a well-known verb -- in the Tools guide, it
is a noun; list items that aren't sentences shouldn't end with periods; "XML"
again; and "run" can be either a participle or a verb, so it should be
disambiguated.)
Paragraph 3: The following might be clearer:
See "CREATE FUNCTION statement" in the Derby Reference Manual for the complete
syntax needed to declare Derby-style table functions. The following topics
provide information on how to write Java methods that wrap foreign data sources
inside ResultSets.
cdevspecialtfbasic.html:
Paragraph 2: Do you think "may be stubbed out and simply raise exceptions" will
be completely clear even to non-native speakers of English? I'm wondering if
the following (or something similar) would be clearer:
Most of the ResultSet methods can be written as stubs that do nothing but throw
exceptions.
4th bullet: It's not clear what the XXX in getXXX means until you look at the
linked-to topic. Would it be helpful to say the following?
...Derby calls a getXXX() method on each referenced column, where XXX is the
column's data type.
In the example, you might line up the table data types vertically if you can.
Elsewhere we say "FROM list" instead of "from-list"; also, the passive verbs in
this sentence make it rather convoluted, so how about the following?
To invoke the table function, wrap it with [in??] a TABLE constructor in the
FROM list of a query.
cdevspecialtfgetxxx.html:
I think "data type" is the more common form. Also, in text you'd want to put
"getXXX()" in italics as you do in the parent topic. And in the second
sentence, add "method":
While scanning a Derby-style table function, Derby calls a preferred getXXX()
method for each column, based on the column's data type.
The following table lists the preferred getXXX() method for each Derby data
type.
cdevspecialtfexample.html:
The first sentence is not very substantive. It might be more economical to have
just one sentence saying something like
The following simple table function selects rows from a foreign database.
cdevspecialtfoptimizer.html:
Paragraph 1: I think we usually say "topic" rather than "section".
Bullet item 1: From the point of view of the translator or non-native speaker
of English, "inclines" may be a somewhat unusual word. How about
Therefore, the optimizer is likely to place ...
Bullet item 2: Participial and gerund phrases (such as "Knowing ...") are often
ambiguous. How about
If it knows that a table function is repeatable, the optimizer can place ...
I'm not sure about "siphoning" -- is "putting" incorrect or too boring?
Bullet item 1 (new bullet list): You might spell out "no-argument".
Bullet item 2: Are there javadocs for the VTICosting interface? I'm not sure
they would be available in the commonest (bin) distribution of Derby, since
that has only the JDBC javadocs as far as I know. If they are reachable
somewhere, you might provide a pointer. I think you've done a great job
providing all the information people need, though.
It might be helpful to add xref links in the second sentence as follows:
This involves implementing the following methods, as described in Measuring the
cost of Derby-style table functions and Example VTICosting implementation:
Even though the generated HTML includes links to those subtopics at the end of
this topic, it would still be reassuring to clarify that the needed info is
available there.
In the three sub-bullets, you might want to change "This" to "This method".
First sub-bullet: I don't see any mention of STARTUP and SCAN in the two
subtopics. What is the relationship between these terms and the values
mentioned in "Measuring the cost of Derby-style table functions"? The value
returned by getEstimatedCostPerInstantiation() doesn't look like a sum of two
values to me, so I'm a bit confused.
cdevspecialtfopttune.html:
You might want to create some sections within this topic, because right now the
transitions from one part to another are not entirely clear. For example, you
might put the part beginning "We treat optimizer Imprecision as a constant ..."
in a section called "Calculating the optimizer's Imprecision", and you might
put the part beginning "The following formula explains how to compute the
Actual runtime cost ..." in a section called "Calculating the Actual run time
for the table function". Finally. you might put the part beginning "Putting all
of this together ..." in a section called "Computing the value returned by
getEstimatedCostPerInstantiation()".
"Short-circuit" bullet: Would it be helpful to give an example of how to do
this? Would all of your audience know? Also, I think "next()" should be in
italics. And "table function" is not capitalized elsewhere in this topic, so
should it be capitalized here?
"Record" bullet" (two occurrences): Should VTIResultSet be in italics?
At the end, since you've broken down the A value, wouldn't it be consistent to
break down the I value too? That would make the formula
C = O/T * [ ( P * N ) + E ]
cdevspecialtfoptexample.html:
Paragraph 1: Again, saying that something is easy is not very substantive (and
may not have the reassuring effect that was probably intended). Maybe something
like
Once you have measured your table function's cost, you can write the VTICosting
methods.
Reference Manual comments:
rrefcreatefunctionstatement.html:
In the TableType section, again, you might want to cut "the section on" and
just say
For more information, see "Programming Derby-style table functions" in the
Derby Developer's Guide.
In the third paragraph of the ParameterStyle section, I don't think
DERBY_JDBC_RESULT_SET and JAVA need to be in italics here.
rrefsqljtfinvoke.html:
I assume you made a deliberate decision to place this new topic as a subtopic
of "TableViewOrFunctionExpression" rather than to move it up to the "SQL
identifiers" topic, where all the other xrefs in the syntax statement can be
found (table-Name, view-Name, etc.). If the parent topic will always be the
only topic that refers to this topic, that makes sense, I guess. However, I
believe this is a deeper level of topic nesting than occurs anywhere else in
this manual.
DITA note: I believe an example element can contain paragraphs, so you don't
have to structure the topic example/section/example; it can be all one example
with a paragraph in the middle. Unimportant, though; doesn't affect the look of
the output.
> User documentation for Table Functions
> --------------------------------------
>
> Key: DERBY-3072
> URL: https://issues.apache.org/jira/browse/DERBY-3072
> Project: Derby
> Issue Type: New Feature
> Components: Documentation
> Reporter: Rick Hillegas
> Assignee: Rick Hillegas
> Attachments: derby-3072-01-basic-aa.diff, derby-3072-01-basic-aa.tar
>
>
> This issue tracks changes to the user guides to describe table functions.
> This is the work needed for the "Documentation" section of the functional
> spec attached to DERBY-716.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
