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 Mon, 30 Oct 2006 23:52:27 GMT
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
-- 
Laura Stewart

Mime
View raw message