db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Laura Stewart" <scotsmat...@gmail.com>
Subject Re: Docs: Explain the types of DITA topics used in Derby documentation
Date Wed, 25 Oct 2006 20:19:46 GMT
Hi Kim -
I've embedded responses below.

On 10/20/06, Kim Haase <Camilla.Haase@sun.com> 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

Mime
View raw message