Return-Path: Delivered-To: apmail-db-derby-dev-archive@www.apache.org Received: (qmail 35775 invoked from network); 5 Dec 2006 19:54:18 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2) by minotaur.apache.org with SMTP; 5 Dec 2006 19:54:18 -0000 Received: (qmail 60798 invoked by uid 500); 5 Dec 2006 19:54:25 -0000 Delivered-To: apmail-db-derby-dev-archive@db.apache.org Received: (qmail 60775 invoked by uid 500); 5 Dec 2006 19:54:25 -0000 Mailing-List: contact derby-dev-help@db.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: Delivered-To: mailing list derby-dev@db.apache.org Received: (qmail 60766 invoked by uid 99); 5 Dec 2006 19:54:25 -0000 X-ASF-Spam-Status: No, hits=0.0 required=10.0 tests= X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO brutus.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 05 Dec 2006 11:54:25 -0800 Received: from brutus (localhost [127.0.0.1]) by brutus.apache.org (Postfix) with ESMTP id 281117142E1 for ; Tue, 5 Dec 2006 11:53:23 -0800 (PST) Message-ID: <13084832.1165348403161.JavaMail.jira@brutus> Date: Tue, 5 Dec 2006 11:53:23 -0800 (PST) From: "Laura Stewart (JIRA)" To: derby-dev@db.apache.org Subject: [jira] Commented: (DERBY-1972) Working With Derby needs some formatting fixes and other minor cleanup In-Reply-To: <7742054.1161108215669.JavaMail.jira@brutus> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 7bit X-Virus-Checked: Checked by ClamAV on apache.org [ 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: Welcome to ! To help you get up and running with as quickly as possible, this self-study guide highlights some of the more important features of

This guide uses a series of activities designed to demonstrate the use of in the embedded and client/server configurations. After performing these activities, you will find to be an easy-to-use and fully functional RDBMS.

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:
Activity 1:
Use the ij tool to load the embedded driver and start the database engine. Create the database firstdb and the table FIRSTTABLE. Use a few basic SQL commands to insert and select data. The message log derby.log and the database directories and files are introduced.
Activity 2:
Use within a client/server configuration. Start the Network Server, which will embed the engine. In a separate process, use the ij tool to load the client driver and connect to the Server. Create a database called seconddb and the table SECONDTABLE. Use a few basic SQL commands to insert and select data.
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 indicates the location of the 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 embedded driver to create and connect to the database firstdb. 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.
Description of connection command: connect 'jdbc:derby:firstdb;create=true';
connect
The ij command to establish a connection to a database. The connection URL is enclosed in single quotation marks.
jdbc:derby:
The JDBC protocol specification for the driver.
firstdb
The name of the database; this can be any string. Because no filepath is specified, the database is created in the default working directory (DERBYDBS).
;create=true
The URL attribute used to create databases. does not have an SQL create database command.
;
The semicolon is the ij command terminator.
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 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 tag in inappropriate places and the use of formatting tags within 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