Hi Kim - I've embedded responses below. On 10/20/06, Kim Haase <[EMAIL PROTECTED]> wrote:
Hi, Laura,
I'd suggest sticking to an 80-character line length for easy readability in text editors, if possible.
Thanks, my editor does not have an issue with the character length and auto word wraps. I appreciate you pointing this out (and fixing the comment lengths) I will watch this in the future and would appreciate it if you see and "stragglers" :-)
Some questions: Under INDEX ENTRIES, would it make sense to provide the URL of the Derby Documentation page? Also, do we recommend a maximum nesting level for index entries (2?)?
Good idea. I assume that we can add a link in a comment. Once I get the link I will add it into the template. But I need to generate the new "Guidelines" page first to get the link. As for the levels for nesting index entires, I think 2 is a good recommendation. Sometimes 3 are used, but not the norm. And certainly NEVER more than 3. Okay with you?
Do you want to include the <stepresult> and <result> tags? The <stepresult> one is used pretty often in our docs, the <result> one only occasionally.
I added the stepresult and result tags and indicated that they are optional.
About not bolding the text inside a codeblock -- are you suggesting that we not provide any distinction between user input and system output? I think the doc conventions make that distinction in most places I have worked, and not making the distinction would be very confusing in Working With Derby, where the example intersperses input and output. Currently, bolding the user input in a codeblock works as long as the system output is not also tagged -- the bug in the toolkit involves the loss of white space *between* tags only, apparently.
I don't think that bolding the entire text in codeblocks is necessary. The monospace font distinguishes the codeblock text from the surrounding text font. I am not saying that there shouldn't be any formatting of the text in the codeblock. The formatting depends on what is in the codeblock. For SQL commands I use uppercase for the command syntax and lowercase for the user input. I tend to use varname for the user input also (which displays italic) For example: CREATE TABLE <varname>tablename</varname> For command line commands I tend to use lowercase except for variable names. I tend to use varname for any user input. In the example below a case could also be made to use filename (which I don't believe changes the output display). For example: set DERBY_HOME=<varname>C:\derby</varname> I see in Working with Derby that the user input and system response are listed in the same codeblock. The system responses seem to be in italic. There are a few ways to approach this: 1) Separate the user input and system responses in separate codeblocks with lead in text for each. 2) Indicate at the top of the sequence that the system responses are in italic. For example: Run the Derby ij tool. In the following examples, the responses from Derby are displayed in italic. I can go either way, but prefer #2 for flow and continuity. My only concern is that for accessibility, a voice reader will not distinguish between the user input and response. Which might make the example unclear to people with disabilities.
About the example codeblock in a substep -- is there a reason for all the spaces between CREATE TABLE and tablename? Was there supposed to be a line break and indent somewhere, or something like that?
There was an extra space, which I have removed.
About choicetables -- I have made the unpleasant discovery that DITA allows you to put them in a step but not in a substep. In some cases I need them in substeps! So I use a simpletable in substeps -- but those look different from choicetables, especially in HTML. And actually, choicetables look kind of ugly in HTML: no vertical space top or bottom, and no vertical lines separating the two columns, which are very close together. I wonder if we need a toolkit fix. Failing that, maybe we should use simpletable everywhere just for consistency in appearance. :(
I would prefer to use choice tables. Let's first see if the new 3.1 toolkit will make them look better, otherwise we can update the style sheet to make them appear better.
Anyway, I've attached a slightly revised version with the 80-character lines and a few corrections of typos here and there.
Thank you for the corrections to typos and the 80 character check.
Thanks a million for doing this. I look forward to the other templates. And the other big job will be to come up with some guidelines for elements that can occur in text -- there are so many! Kim
-- Laura Stewart
