[
http://issues.apache.org/jira/browse/DERBY-1972?page=comments#action_12455743 ]
Laura Stewart commented on DERBY-1972:
--------------------------------------
Let's try this again...
Hi Kim -
Thanks for including the DITA files, my ol' eyes can read those files much
easier than the diff files :-)
You have made some great improvements in the tagging and formatting. Some of
the formatting you use (pre for example) is not what I am used to, and I think
we need to discuss what we want to promote/recommand as we go forward with more
edits to the Derby doc files. But for the most part I think we are on the same
page and use most the same tags.
Here are my comments:
PDF copyright (page 4) appears run together. I would ask about this on
derby-dev and perhaps someone like Andrew can fix it. he copyright info on
page 5 is just fine.
All of the files seem to have a comment at the top with a date of the
"contribution". The dates seem to be from earlier this year. Also there is a
rev attribute on the first tag. Do you think that we should maintain the
contribution date or remove it? Are you using the rev attribute?
File = twwdIntro.dita (Introduction and prerequisites)
The shortdesc seems really long. How about this:
<shortdesc>
Welcome to <ph conref="wwdconrefs.dita#prod/productshortname"></ph>! To help
you get up and running with <ph
conref="wwdconrefs.dita#prod/productshortname"></ph> as quickly as possible,
this self-study guide highlights some of the more important
features of <ph conref="wwdconrefs.dita#prod/productshortname"></ph>
</shortdesc>
<p>
This guide uses a series of activities designed to demonstrate the use of <ph
conref="wwdconrefs.dita#prod/productshortname"></ph> in
the embedded and client/server configurations. After performing these
activities, you will find <ph
conref="wwdconrefs.dita#prod/productshortname"></ph> to be an easy-to-use and
fully functional RDBMS.
</p>
Also, should we assume that Derby users understand the abbreviation RDBMS? I
am thinking specifically about people for whom English is not their first
language.
The index terms for this file are a little vague. How about these:
Java Development Kit version
validating
JDK version
validating
Working with Derby activities
prerequistes
prerequistes
Working with Derby activities
environment variables
verifying
JAVA_HOME environment variable
verifying
DERBY_HOME environment variable
verifying
"website" should be "Web site".
I don't like the way that the text in the steps runs together. I tried to fix
it but there must be something that we need to change in the CSS or elsewhere
to get better formatting. I don't know how to fix this now, but we need to
address it for the html output. Maybe a goal for 10.3? We also need to fix the
formatting in the choice tables. The text in the second columns is always 1
line below the text in the first column. I would prefer to use
choice tables in the steps but let's leave the simple tables in there for now
until we can figure it out.
Step 1 - In one place you use userinput and another codeph. In another place
you use userinput and systemoutput. I have consistenly used codeph inline in
paragraphs and codeblocks in choicetables and for blocks of code. They all
produce monospace and there is no formatting difference between them. Is there
a reason that you think we should use each of these tags. If we were in an
proprietary project where doc contributors are all tech writers, or if these
tags actually produced formatting differences, then I would be all for using
unique tags (in the hopes that some day the formatting would be unique between
the text - aka DITA flexibility). But I am concerned overburdening our open
source contributor with too many different tags to learn...
Why do you use the "pre" tag? In many cases I don't think that it is necessary.
"via" is latin based and can cause problems with translation. It should be
changed to ""by using".
File = cwwdactivities.dita (Activity overview)
There are no index entries. How about adding this index entry:
Working with Derby activities
overview
There is a definition list here that doesn't appear to be used properly. There
are empty dt tags and a series of dd tags with paragraph tags inside. It would
be best if it was formatted like this:
<dl>
<dlentry>
<dt>Activity 1:</dt>
<dd>Use the <ph conref="wwdconrefs.dita#prod/productshortname"></ph>
<codeph>ij</codeph> tool to load the <ph
conref="wwdconrefs.dita#prod/productshortname"></ph> embedded driver and start
the <ph conref="wwdconrefs.dita#prod/productshortname"></ph> database engine.
Create the database <i>firstdb</i> and the table FIRSTTABLE. Use a
few basic SQL commands to insert and select data. The <ph
conref="wwdconrefs.dita#prod/productshortname"></ph> message log
<i>derby.log</i> and the database directories and files are introduced.
</dd>
</dlentry>
<dlentry>
<dt>Activity 2:</dt>
<dd>Use <ph conref="wwdconrefs.dita#prod/productshortname"></ph> within a
client/server configuration. Start the <ph
conref="wwdconrefs.dita#prod/productshortname"></ph> Network Server, which
will embed the <ph conref="wwdconrefs.dita#prod/productshortname"></ph> engine.
In a separate process, use the <ph
conref="wwdconrefs.dita#prod/productshortname"></ph> <codeph>ij</codeph> tool
to load the <ph conref="wwdconrefs.dita#prod/productshortname"></ph> client
driver and connect to the Server. Create a database called <i>seconddb</i> and
the table SECONDTABLE. Use a few basic SQL commands to insert and select data.
</dd>
</dlentry>
This automatically puts the activity number in bold and you only need to use
paragraph tags if you need a second paragraph for the activity description.
If you want to use italic for things like the database name and the message log
name you can. The most logical tag for an object name is filepath, but it
doesn't display any format. The only other tag to display italic is varname,
but this isn't really a variable. I often use codeph. Your choice, until we
figure out the best tag and formatting :-)
File = twwdactivity1_Setup.dita
I don't think that the indexes here are helpful. If you want to hold off on
changing this, we can do an "index blitz (probably early next year?) on all of
the files. I intend to do one on the Ref Guide before the end of the year.
Is filesystem one word?
An overall design question... I usually see the step include the appropriate
command example. The way that it is currently layed out, the steps are listed
followed by an example of all of the commands together in a large table. So the
user reads step 1 and thinks, okay what do I do now? I can't go to step 2
until I finish step 1. Is there a reason that you prefer this other
arrangement?
There is a sentence just before the steps that I think should be changed:
Be sure to adjust these commands so that <ph
conref="wwdconrefs.dita#prod/productinstallpath"></ph> indicates the location
of the <ph conref="wwdconrefs.dita#prod/productshortname"></ph> installation on
the system being used.
I think that we need to be more direct and change the phrase "on the system
being used" to "on the system that you are using".
There should be periods at the end of each step.
File = twwdactivity1.dita
There is no shortdesc in this file and it seems odd to launch right into the
steps. You can steal part of the shortdesc from the twwdactivity1_Setup.dita
file. Here is the text that I would move to the twwdactivity1.dita file:
You will use the <ph conref="wwdconrefs.dita#prod/productshortname"></ph>
embedded driver to create and connect to the database <i>firstdb</i>. You will
also use a few basic SQL commands.
Try to avoid using the word "it", which isn't specific. You can see this
especially in step 9. Is "it" referring to message or the error log file?
I think that the "Description of connection command" should be moved to the end
of step 2. Also the tagging in the definition list is not what I am used to.
It is my understanding that for each dl there is one dd. But you can next
definition lists. Added a few words and changed the formatting in the
following example. For example, I tend to use "quotation marks" instead of
"quotes" for better translation and to avoid slang.
<dl>
<dlentry>
<dt>Description of connection command: <codeph>connect
'jdbc:derby:firstdb;create=true';</codeph></dt>
<dd>
<dl>
<dlentry>
<dt><codeph>connect</codeph></dt>
<dd>The <codeph>ij</codeph> command to establish a connection to a database.
The <ph conref="wwdconrefs.dita#prod/productshortname"></ph> connection URL
is enclosed in single quotation marks.</dd>
</dlentry>
<dlentry>
<dt><codeph>jdbc:derby:</codeph></dt>
<dd>The JDBC protocol specification for the <ph
conref="wwdconrefs.dita#prod/productshortname"></ph> driver.</dd>
</dlentry>
<dlentry>
<dt><codeph>firstdb</codeph></dt>
<dd>The name of the database; this can be any string. Because no filepath
is specified, the database is created in the default working directory
(<i>DERBYDBS</i>).</dd>
</dlentry>
<dlentry>
<dt><codeph>;create=true</codeph></dt>
<dd>The <ph conref="wwdconrefs.dita#prod/productshortname"></ph> <varname>URL
attribute</varname> used to create databases. <ph
conref="wwdconrefs.dita#prod/productshortname"></ph> does
not have an SQL <codeph>create database</codeph> command.</dd>
</dlentry>
<dlentry>
<dt><codeph>;</codeph></dt>
<dd>The semicolon is the <codeph>ij</codeph> command terminator.</dd>
</dlentry>
</dl>
</dd>
</dlentry>
</dl>
File = twwdactivity2.dita
Again, I don't think that the indexes here are helpful.
Prereq tag includes this text "This activity assumes that you know how to..."
and at then end talks about the env variable. I think that you might want to
reword this last part since in an earlier part of this book they have set the
variable. Maybe say something like "... directory, and have already set the
<ph conref="wwdconrefs.dita#prod/productinstallpath"></ph> environment variable.
Try to avoid contractions like "we'll" and vague words like "them"
Step 9. It might be better to say "Select a subset of records from the table by
specifying a WHERE clause."
File = twwdactivity3_Setup.dita
The shortdesc is really long. Can you move some of that to the context section?
Should the index term be "WwdEmbedded.java program" instead of just
"WwdEmbedded.java" ?
In the IMPORTANT note, I would remove the word "Only" and add the acronym or
use the acronym instead of spelling out the name (since I believe that it is
mentioned in the Introduction?
File = twwdactivity3.dita
Same comment here about the index term "WwdEmbedded.java"
Define key variables and objects section has a ul that seems like it should be
a dl. Do you typically use ul to introduce part of a syntax followed by a dash
and the explanation?
Should the method names be in italic or monospace? We should probably decide on
this an add it to the Doc FAQ or Guidelines Web page (because I know that I
will forget :-)
File = twwdactivity4.dita
I think that shortdesc is long in this file too. Can you move some of that to
the context section?
Should the index term be "WwdClient.java program" instead of just
"WwdClient.java" ?
Steps - I don't think that you need to bold the text in the cmd tag. If you
want to indicate that there are substeps, add the text "using the following
steps:"
Try to avoid contractions like "we'll". Maybe reword to "Open a command window
that we will use as the Client-Shell command window."
In the IMPORTANT note, I would remove the word "Only"
File = cwwdsummary.dita
In most of the writing that I do, we avoid the use of word "we". Is that true
at SUN? If so, then there are several places that the text should be reworded.
> Working With Derby needs some formatting fixes and other minor cleanup
> ----------------------------------------------------------------------
>
> Key: DERBY-1972
> URL: http://issues.apache.org/jira/browse/DERBY-1972
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.2.1.6
> Reporter: Kim Haase
> Assigned To: Kim Haase
> Priority: Minor
> Attachments: DERBY-1747.diff, DERBY-1972-2-dita.zip,
> DERBY-1972-2.diff, DERBY-1972-2.zip, DERBY-1972.zip, DERBY_1972.diff
>
>
> The Working With Derby book uses DITA tags in ways that are not always
> consistent with the usage in other books and that lead to some problems in
> the processed output. Some examples are the use of the <varname> tag in
> inappropriate places and the use of formatting tags within <codeblock> tags.
> There are also a few minor punctuation and syntax issues worth fixing.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
