Mailing-List: contact derby-dev-help@db.apache.org; run by ezmlm
Precedence: bulk
Reply-To: <derby-dev@db.apache.org>
Received-SPF: pass (asf.osuosl.org: domain of scotsmatrix@gmail.com designates
 64.233.182.187 as permitted sender)
DomainKey-Signature: a=rsa-sha1; q=dns; c=nofws;
        s=beta; d=gmail.com;
        h=received:message-id:date:from:to:subject:in-reply-to:mime-version:content-type:content-transfer-encoding:content-disposition:references;
        b=KPxQwbTlnbcgthBRWZ1gcw0rqtaW0x9HrlPQvGIZmItUp9UlpEby5mmU8rA0OBBVQghgJoqQlp0PUdC1d5of3n8s7QmeRYgTmB6rA8zbF/FOQgmUyvTtWPANGg//NHi/9+hzNikELv5AW4bXfksu1SJlSNvrSf92KfdVcg7tXww=
Message-ID: <9f40b500608291331j37408c6eu81532229efccaaf@mail.gmail.com>
Date: Tue, 29 Aug 2006 13:31:08 -0700
From: "Laura Stewart" <scotsmatrix@gmail.com>
To: derby-dev@db.apache.org, jta@bristowhill.com
Subject: Re: XML type description - possible changes?
In-Reply-To: <44F49C20.7050508@bristowhill.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
Content-Disposition: inline
References: <44F3B588.4020405@apache.org> <44F476EE.5050209@gmail.com>
	 <44F479C2.1050204@apache.org>
	 <9f40b500608291130h625aefc6kff40bac794e55f5@mail.gmail.com>
	 <44F49C20.7050508@bristowhill.com>

On 8/29/06, Jean T. Anderson <jta@bristowhill.com> wrote:
> Laura Stewart wrote:
> ...
> > FYI - I would prefer to keep the phrase "data type" in the title and
> > first paragraph of this file as a qualifier.  In the near future (post
> > 10.2) I intend to update all of the other files that describe data
> > types to add this qualifier.  There are many files in Derby that don't
> > have qualifiers in the titles and it makes locating the correct info
> > difficult for Derby users.
>
> I don't agree with this change. I wouldn't like to see everything
> expanded -- "BLOB data type", "Date data type", etc.
>
> The XML data type appears in the "Data Types" chapter -- I haven't heard
> any users complain that this isn't clear. But I may have missed some
> posts. Could you include a link to the posts that showed the difficulty?
>
> thanks,
>
>  -jean

One of the benefits of using DITA is that the documentation is
"componentized" into "topics".
There are several benefits to this:
-- Combined with the information from other products
-- Alternative ways to view the information.

COMBINED INFO
When another products are combined with Derby, the information for
those products can  be combined with the information for Derby. It is
important that the titles of the topics state clearly what the topic
is about.  When users look at a Table of Contents or Navigation Tree
to find information, the qualifiers help users find the information
that they want more quickly.  Adding the qualifiers also helps  people
for whom English is not their native language. In this case, we are
describing different data types and that qualifier should be applied
to the title.  What if there is a topic entitled XML which discusses
the data type, and another topic entitled XML which describes an
overview of the Extensible Markup Language, and a third topic entitled
XML which describes what "well-formed" XML documents are.  In this
example 3 topics with the same title is confusing. And while the
topics appear in different sections in a book (which might help
distinguish the topics), that implied qualifer doesn't help when the
information is viewed in a different way (see below).

METHODS OF VIEWING INFO
Another advantage of DITA is the ability to view the documentation in
different ways.  It can be viewed in the traditional PDF/Book format
or it can be viewed in non-traditional ways, such as is categories of
information or by subject matter (such as all troubleshooting info).
Viewing information in categoies is often the way information is
organized in Information Centers. In Info Centers, the organization of
the information is often not in the sequential book format.  In these
situations, the implied qualifier of the chapter or section title is
always present for a topic.

Bottom line. Topics need to be able to stand alone. Their titles
should be clear and concise and they should have links to the
appropriate information.

So I don' t have any links to specific Derby posts about this. I am
just explaining what the trend is in technical writing and
information.

-- 
Laura Stewart