db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Jean T. Anderson" <...@bristowhill.com>
Subject Re: XML type description - possible changes?
Date Tue, 29 Aug 2006 20:42:03 GMT
This sounds like a larger style issue that should be tackled post 10.2.
In the meantime, let's be consistent with current usage.


Laura Stewart wrote:
> 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.
> 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).
> 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.

View raw message