Fwd: Re: DITA markup for meaningful words

[Bruce Esrig <esrig-ia@esrig.com>]

Re-sending ...

Date: Sun, 06 May 2007 21:06:41 -0400
To: <dita-fa-edboard@lists.xml.org>
From: Bruce Esrig <esrig@alumni.princeton.edu>
Subject: Re: DITA markup for meaningful words
Cc: ehennum@us.ibm.com

More thoughts on Amber's article ... this ought to be a TC discussion, perhaps, but unfortunately, I haven't been able to attend those meetings in a while.

In order to move the discussion forward, I combed through the DITA 1.1 language specification, and came up with two tables. The first table is from markup to use. The second table is the useful one, from use to markup.

An article based on the second table could help a lot.

As a side issue, the DITA 1.1 architecture document could use some text on "properties" that provides the background for the <data> element.

Best wishes,

Bruce

At 04:11 PM 5/3/2007, Bruce Esrig wrote:

Amber's article reawakened a bunch of old issues for me, and that's before I gave it a careful reading!

So here is a substantial excerpt, with occasional new thoughts, of the rather spontaneous remarks that I sent her moments ago.

Best wishes,

Bruce

============

We need to do a more deliberate use case analysis and conceptual architecture before we try to advise users on <keyword> ... I'd rather see a broader treatment of: meaningful words, what authors need to do with them in order to help readers, and what mechanisms and conventions are available for meeting these needs of the authors.

I think there's a basic triumvirate (let's start with that) of purposes for which meaning-carrying elements can be introduced: metadata, indexing, and talking to the user.

The <data> element holds metadata. One use of <keyword> does this too. What do we recommend? Can we say that the <data> element is the canonical way, and <keyword> is preserved for backward compatibility?

We have <indexterm> for throwing concepts into an index. We have the indexing best practice for showing how to use <indexterm>. Does that indicate how to coordinate <indexterm> with the second use of <keyword> (the one that generates printable output)?

The first kind of talking to the user is introducing a concept. If I'm recalling correctly, <term> in DITA marks a term *use*. <glossentry> provides a definition. Does DITA processing link them?

Last, when talking to the user with simple content, <keyword> is a base for specialization. As Amber points out, it does generate metadata, but I don't think the user can control where the metadata gets propagated to, and there's a separate mechanism for indexing. Maybe the right way is to show a rewrite: the effect of <keyword> in content is the same as (let's say) the following combination: a <data> element in the metadata that points to a <term> in the content.

I think this is a serious problem that calls for a user guide. But it should be a semantically-driven user guide. What are the contexts in which terms can appear (ignoring markup) and the purposes that they can serve in those contexts? What support is needed in the language to ensure that those purposes can be achieved? Finally, what are the idioms in DITA for achieving those purposes?

At 08:19 PM 5/2/2007, Amber Swope wrote:

Hi there,
I haven’t heard any feedback from anyone, so I wanted to make sure that this email actually reached the board. One (or more) of the following situations may be the case:

• You didn’t receive it.
• You received it and thought it was perfect.
• You received it and were too busy to review it.
• You received it, reviewed it and were too busy to send me feedback.
• You received it, reviewed it, hated it and were struggling with how to break the bad news to me.

 
Just in case the first bullet is the case, I’ve attached the article draft again.
 
Thanks, A

---

From: Amber Swope
Sent: Monday, April 30, 2007 8:45 AM
To: JoAnn Hackos; Carol Geyer; dita-fa-edboard@lists.xml.org
Subject: RE: [dita-fa-edboard] Traffic Report for DITA XML.org site
 
Here is the draft. Some things to note:
·         Once I started working on the article, I realized that it would be too long if I tried to address keywords and index entries, so I focused on keywords.
·         I would appreciate any suggestions for better keywords to use in the examples.
·         I used <codeblock> for all my examples, but if someone can suggest a better element to use for the generated output (=non-markup) examples, I’d be happy to use it.
·         I would love any input on the Why section, especially about the Web metadata. From the folks I talked with, the story is that many search engines do not use this metadata because of the optimization engines that manipulate the data.
Of course, any other feedback that would improve the article is welcome.
Thanks, A
 
-----Original Message-----
From: JoAnn Hackos [mailto:joann.hackos@comtech-serv.com]
Sent: Monday, April 30, 2007 8:40 AM
To: Amber Swope; Carol Geyer; dita-fa-edboard@lists.xml.org
Subject: RE: [dita-fa-edboard] Traffic Report for DITA XML.org site
 
XML works for me
 
JoAnn T. Hackos, PhD
President
Comtech Services, Inc.
710 Kipling Street, Suite 400
Denver, CO 80215
303-232-7586
joann.hackos@comtech-serv.com
joannhackos Skype
www.comtech-serv.com
 
-----Original Message-----
From: Amber Swope [mailto:amber.swope@xmetal.com]
Sent: Monday, April 30, 2007 9:02 AM
To: JoAnn Hackos; Carol Geyer; dita-fa-edboard@lists.xml.org
Subject: RE: [dita-fa-edboard] Traffic Report for DITA XML.org site
 
Hi there,
The good news is that I have the first draft of the next article ready
for your review. Of course, I wrote it in XML and can provide it in all
the usual formats for review. What format is best?
 
Thanks, A
 
-----Original Message-----
From: JoAnn Hackos [mailto:joann.hackos@comtech-serv.com]
Sent: Monday, April 30, 2007 6:44 AM
To: Carol Geyer; dita-fa-edboard@lists.xml.org
Subject: RE: [dita-fa-edboard] Traffic Report for DITA XML.org site
 
Interesting -- we're seeing a regular decline. Probably need to have new
content.
JoAnn
 
JoAnn T. Hackos, PhD
President
Comtech Services, Inc.
710 Kipling Street, Suite 400
Denver, CO 80215
303-232-7586
joann.hackos@comtech-serv.com
joannhackos Skype
www.comtech-serv.com
 
-----Original Message-----
From: Carol Geyer [mailto:carol.geyer@oasis-open.org]
Sent: Monday, April 30, 2007 8:02 AM
To: dita-fa-edboard@lists.xml.org
Subject: [dita-fa-edboard] Traffic Report for DITA XML.org site
 
DITA XML.org Editorial Board,
Attached are site stats for April. We may want to discuss these on our
next
call.
Carol
 
_________________________________
Carol Geyer
Director of Communications
OASIS
+1.978.667.5115 x209
 
 
 
 
---------------------------------------------------------------------
This publicly archived list is provided by OASIS for the use of the
Editorial
Board of DITA XML.org. Subscription and posting privileges are reserved
for
members of the Editorial Board; others should contact
communications@oasis-open.org for assistance.
 
[Un]Subscribe: dita-fa-edboard-[un]subscribe@lists.xml.org
List archives: http://lists.xml.org/archives/dita-fa-edboard/
XML.org DITA Focus Area: http://dita.xml.org
Committee homepage: http://www.oasis-open.org/committees/dita
List Guidelines: http://www.oasis-open.org/maillists/guidelines.php
 
 
 

---------------------------------------------------------------------
This publicly archived list is provided by OASIS for the use of the Editorial
Board of DITA XML.org. Subscription and posting privileges are reserved for
members of the Editorial Board; others should contact
communications@oasis-open.org for assistance.

[Un]Subscribe: dita-fa-edboard-[un]subscribe@lists.xml.org
List archives: http://lists.xml.org/archives/dita-fa-edboard/
XML.org DITA Focus Area: http://dita.xml.org
Committee homepage: http://www.oasis-open.org/committees/dita
List Guidelines: http://www.oasis-open.org/maillists/guidelines.php

keywords-20070506.doc