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 <[EMAIL PROTECTED]> 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 OVERALL - 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. NEW TERMS - 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? FILE NAMES/PATHS - 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
