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: Documentation conventions, DITA, and the toolkit
Date Mon, 13 Nov 2006 19:28:51 GMT
Kim -

Thanks for your thoughtful work on this. Since you have a lot of
comments, I am going to respond to each section/piece separately.

Section - Overall, New Terms, File Names/Paths

On 11/8/06, Kim Haase <Camilla.Haase@sun.com> wrote:
> This note is on a subject that could feed into the Guidelines doc,
> especially the parts about textual tags as opposed to structural tags.
> The Getting Started manual has a section called "Typographical
> conventions"
> (http://db.apache.org/derby/docs/dev/getstart/rgsdocs18277.html) that
> describes documentation conventions for the Derby manuals. It may need
> some refining. And then how to make the conventions happen in DITA leads
> to some toolkit questions. The goal of the section should be to describe
> the way things mostly are, so that we can try to encourage contributors
> to be consistent in the future. Fixing what's there now is a lower
> priority goal. I would appreciate your views, Laura, and those of anyone
> who's had longer experience with the docs than I have (most of you, I
> think).
> New terms in italic: this is fine. The DITA <term> tag seems to
> translate into a <dfn> tag in HTML.
> File and directory names in italic: this is a somewhat unusual
> convention in my experience (fixed-width is more common, I think), but
> I'd feel better about it if the documentation used it consistently. But
> even the Getting Started manual doesn't. I think this may be a toolkit
> issue, because Getting Started uses <filepath> instead of <i>, and the
> <filepath> tag currently seems to translate into ordinary text font
> (<span class="filepath">, with no available css file to define the
> class). (The 3 css files that are copied into the output directory don't
> define this class.)

Discussion - Overall, New Terms, File Names/Paths

I agree, we need to look at what is documented here and see what needs
to be updated or added. I also think that it would be beneficial for
the typography info to be included on the Web, wherever it is not
already discussed. And on the Web there should be some info about
tagging, but that should not be in the docs.

Yes, the <term> tag is the correct one to use in DITA.  There should
probably be some guidelines on the Web as to what constitutes a new
term.  Any thoughts on this?

I like it when they appear in italic but the <filename> tag does not
appear to use that format.  I don't know very much about the CSS and
if we can change it to whatever format we want.  Do you know of a site
that gives a tutorial on style sheets?

I'll respond to the other sections as I have time.

Laura Stewart

View raw message