Laura Stewart wrote On 10/30/06 18:52,: > On 10/30/06, Laura Stewart <[EMAIL PROTECTED]> wrote: > >>On 10/30/06, Laura Stewart <[EMAIL PROTECTED]> wrote: >> >>>We need to decide just how many DITA tags the Derby documentation >>>should use. There are dozens of tags that writers will be very >>>familiar with, but do we really want to encumber an open source >>>community with using all of those tags. >>> >>>I think that to encourage more people to write documentation in DITA >>>that we need to highlight the most important tags for them to become >>>familiar with. >>> >>>Please take a look at the updated Derby Documentation web pages, specifically >>>http://db.apache.org/derby/manuals/guidelines.html and the DITA Source pages. >>>The Writing Guidelines page is new. I would like to list the most >>>essential tags people might want to know... the ones that we want to >>>encourage people to use consistently when updating existing topics. >>>The templates will show them the tags (mostly) that they need when >>>creating new topics, so I don't want to necessarily repeat all of >>>those tags. >>> >>>I'm thinking that we highlight the "top ten" most commonly used tags. >>>What would be on your top ten list? >>> >>>-- >>>Laura Stewart >>> >> >> >>BTW - According to OASIS >>http://docs.oasis-open.org/dita/v1.0/langspec/pre.html >> >>pre >>The preformatted element (<pre>) preserves line breaks and spaces >>entered manually by the author in the content of the element, and also >>presents the content in a monospaced type font (depending on your >>output formatting processor). Do not use <pre> when a more >>semantically specific element is appropriate, such as <codeblock>. >> >>-- >>Laura Stewart >> > > > Here is my top "??" list. The first 9 seem essential to me (in no > particular order). The middle group are similar in their intent... do > we need each one of them? The last group are some that I have used and > some that I have not (but that we have discussed). I would be > interested in hearing what you think are the essential tags to promote > in Derby. > > 1. dl > 2. note > 3. p > 4. ul > 5. xref > 6. table > 7. codeblock > 8. codeph > 9. indexterm > > 10. cmdname > 11. varname > 12. parmname > > 13. userinput > 14. systemoutput > 15. term > 16. filepath
I've been thinking it may be useful to divide the recommended tags into two categories -- structural tags and body tags might be appropriate terms. There are structural elements like lists, paragraphs, tables, and the like; and there are tags that you use in text within these structural elements, like codeph, term, varname, filepath, and so on. Does that seem helpful? Kim
