db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Laura Stewart (JIRA)" <j...@apache.org>
Subject [jira] Commented: (DERBY-1972) Working With Derby needs some formatting fixes and other minor cleanup
Date Tue, 05 Dec 2006 19:53:23 GMT
    [ 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

        

Mime
View raw message