db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Kim Haase <Camilla.Ha...@Sun.COM>
Subject Re: Docs: Explain the types of DITA topics used in Derby documentation
Date Wed, 01 Nov 2006 22:35:32 GMT
Laura Stewart wrote On 10/30/06 18:52,:
> On 10/30/06, Laura Stewart <scotsmatrix@gmail.com> wrote:
> 
>>On 10/30/06, Laura Stewart <scotsmatrix@gmail.com> 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


Mime
View raw message