[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
RE: [dita-fa-edboard] Minutes: 10 May 2007 DITA XML.org Editorial Board Call
- From: "JoAnn Hackos" <joann.hackos@comtech-serv.com>
- To: "DITA Editorial Board" <dita-fa-edboard@lists.xml.org>
- Date: Mon, 4 Jun 2007 13:41:36 -0600
Bruce,
I'm sending this through the editorial board because I can't send you an
email message at the princeton isp.
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
-----Original Message-----
From: Bruce Esrig [mailto:esrig@alumni.princeton.edu]
Sent: Monday, June 04, 2007 9:28 AM
To: JoAnn Hackos
Subject: RE: [dita-fa-edboard] Minutes: 10 May 2007 DITA XML.org
Editorial Board Call
Hi Joanne,
I did a write-through of the top of the article, moving some ideas up to
make the shortdesc's and intros a little more purposeful. I'll enclose
the raw XML text under my signature.
Also, a wordsmithing item ("each purpose") for the intro article, which
I'll put right here:
> To help authors choose the correct element for each purpose,
Please confirm that my comments reached you ...
Best wishes,
Bruce
-------------
<!-- shortdesc for the outermost concept topic -->
<shortdesc>
In DITA, the <keyword> element and the elements that
specialize from it
contain text that has a unique or key-like value.
This article explains these elements in more detail
and proposes guidelines for how to use them.
</shortdesc>
-------------
<!-- replacement topics for the first few nested topics -->
<concept id="concept_7A3F40D0B45D4C2D9BD4B58A1E01EEA0">
<title>Keywords and the <keyword> element </title>
<shortdesc>
The keyword elements that are available in DITA
cover a wide variety of situations in which terms
must be introduced to the reader. For these
situations,
a variety of specialized elements are provided.
</shortdesc>
<conbody>
<p>
The <keyword> element is used to specify
any of several common types of terms in DITA.
What do all of these elements have in common? They are
elements
designed to contain text "that has a unique or
key-like value"<fn>DITA Release
1.1 Language Specification , page 71</fn>
By "text with a unique or key-like value", we mean
text that has a specific purpose.
You designate a term as a keyword when you want to
indicate
that the term has a special meaning.
</p>
<p>
When used in the metadata of a topic, keywords are
"Terms from a controlled or uncontrolled subject
vocabulary that
apply to the topic."<fn>DITA Release 1.1 Architectural
Specification</fn>
Whether used as metadata or in the body of a topic,
"the <keyword> element identifies a keyword or
token, such as a
single value from an enumerated list, the name of a
command or parameter,
product name, or a lookup key for a message."<fn>DITA
Release 1.1 Language
Specification, page 71
</fn>
</p>
<p>The <keyword> element is a generic element
that is designed to
easily allow specialization. For example, the
<apiname>, <kwd>,
<option>, <parmname>, <cmdname>,
<msgnum>,
<varname> <shortcut>, <wintitle>,
and <shape> elements
are all specializations of the <keyword>
element.
</p>
<p>For example, if you consistently apply the
<wintitle> element for
the names of windows in the graphical user interface,
you can process the
<wintitle> element differently from other text.
If the corporate style is
to format window names as bold text, then you can
specify that the transform
apply bold styling to all <wintitle> elements
upon processing.
</p>
</conbody>
</concept>
<concept id="concept_E62F91C620AE4C3D876E5B4D87FC7EF2">
<title>Why use keywords </title>
<shortdesc>The ability to control output processing for
specific types of
text is one the main reasons to use the <keyword>
element.
</shortdesc>
<conbody>
<p>Another reason for specifying keywords is to aid in
Web content
indexing and retrieval. When the DITA Open Toolkit
(OT) processes DITA topics
and maps to XHTML, it places any <keyword> and
<indexterm> elements
in the Web page metadata. Web metadata is important
because it supports
search/retrieval.
</p>
</conbody>
At 08:31 AM 6/4/2007, you wrote:
>Carol et al.
>As soon as I have a minute this week, I'll review the article again.
>I'll make changes I feel are needed. Last time, they were only copyedit
>changes. Bruce, send any comments to me to incorporate so that we can
>get this posted, probably next week.
>
>Carol, I've been referring people to earlier articles. Where are they
>posted? Is there a way to create a Soapbox area plus reference them
>from the appropriate topic in the KB?
>
>Amber, your in all of our thoughts, I sure. Take care of yourself.
>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
>
>
>-----Original Message-----
>From: Carol Geyer [mailto:carol.geyer@oasis-open.org]
>Sent: Thursday, May 31, 2007 12:08 PM
>To: 'Amber Swope'; 'DITA Editorial Board'
>Subject: RE: [dita-fa-edboard] Minutes: 10 May 2007 DITA XML.org
>Editorial Board Call
>
>Amber,
>The feedback you and Bruce provided on improving the site is great. I'm
>anxious to find the time to discuss your ideas with our IT guys. We
>will keep you in our thoughts and prayers tomorrow.
>
>Editorial Board,
>If Amber's article is ready to go, please let me know and I'll get it
>posted.
>If changes are needed, could someone else on the Board take the lead on
>coordinating those?
>
>Thanks,
>Carol
>
>
>-----Original Message-----
>From: Amber Swope [mailto:amber.swope@xmetal.com]
>Sent: Thursday, May 31, 2007 11:49 AM
>To: Carol Geyer; DITA Editorial Board
>Subject: RE: [dita-fa-edboard] Minutes: 10 May 2007 DITA XML.org
>Editorial Board Call
>Importance: High
>
>Hi there,
>
>First, a quick apology and explanation for my recent silence. I've been
>dealing with some health issues for the past month and am having
>surgery tomorrow. I expect to be in the hospital for 5-7 days, then
>home on a medical leave for at least another week.
>
>Bruce and I met once and had a successful meeting in that we came up
>with some concrete ideas. We were scheduled to meet a second time, but
>I've been too ill to do so. If the initiative cannot wait until later
>in June, then someone else will need to help out.
>
>I've attached the XML markup as well as the generated HTML output for
>the intro to the article series as well as the updated keywords
article.
>Many thanks to those who provided input. If either piece needs
>additional editing, please fix and post them. I'm not able to do any
>more work on them and don't want to hold up their release any longer.
>
>For the poll, maybe we can ask if readers use the <keyword> element?
>
>Thanks, A
>
>
>
>-----Original Message-----
>From: Carol Geyer [mailto:carol.geyer@oasis-open.org]
>Sent: Thursday, May 10, 2007 12:06 PM
>To: 'DITA Editorial Board'
>Subject: [dita-fa-edboard] Minutes: 10 May 2007 DITA XML.org Editorial
>Board Call
>
>Attending: JoAnn (chair), Carol, Scott, Bruce, Amber
>
>
>1. Board discussed traffic stats provided by OASIS webmaster. We are
>concerned about declining traffic numbers, but feel we need more data
>before we can really see a meaningful trend.
>
>Board agreed that getting fresh content on a regular basis is the best
>way to increase traffic. Amber suggested we invite prolific posters
>from the dita-yahoo list to provide a recap of topics that have been
>discussed.
>This
>would not be a continuation of discussion, but simply a summary of the
>dialogue and a link back to the yahoo thread. Bruce suggested we use
>the "blog"
>portion
>of the site for this.
>
>AI: Amber and Bruce will identify the top 20 prolific *and
>knowledgeable*
>posters to the dita-yahoo list
>AI: Edboard to draft invitation and describe what we're asking posters
>to do:
>Goal: Provide easier access to important answers to DITA issues raised
>on the yahoo list
>Task: Summarize an issue discussed on yahoo in a blog entry on DITA
>XML.org, provide a link to the thread.
>
>2. <soapbox>
>Team discussed Amber's article and agreed to expand it as the first in
>a series of articles on "Confusing DITA elements." After "keyword",
>article, the team decided to plan future <soapbox> articles on term,
>index term, phrase, and data. The articles should highlight the fact
>that DITA is an evolving standard and practices may change in the
>future.
>
>AI: Amber to recast "keyword" article and write an intro for the
series.
>
>AI: JoAnn to write next article on index term (due in July or so).
>AI: Amber to invite Eric to co-author future "term/glossaries" article
>with her. Bruce to invite Eric to co-author future "data" article.
>Amber may co-author "phrase" with someone else.
>AI: Edboard members to provide feedback on "keyword" article to Amber
>by the end of the week, especially questions on keywords that would
>stimulate discussion.
>
>Next call:
>14 June 2007
>2:00 pm EST
>+1 (605) 990-0700, access code: 562542*
>
>
>_________________________________
>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
>
>
>
>
>---------------------------------------------------------------------
>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
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
