Keywords: why, where and when to use them

["Amber Swope" <amber.swope@xmetal.com>]

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

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<!-- Created with XMetaL (http://www.xmetal.com) -->
<concept id="concept_B53B5D0F8C8848978E10D769D3BA5696">
  <title>Keywords: why, where and when to use them</title> 
  <shortdesc> According to Wikipedia, a keyword "is a word or concept with
	 special significance." This definition is a very broad; it emcompasses a wide
	 range of uses. This article explains what keywords are in DITA and proposes
	 guidance for keyword usage.
  </shortdesc> 
  <prolog> 
	 <metadata>
		<keywords><keyword>keyword</keyword><keyword>test</keyword>
		</keywords></metadata>
  </prolog>
  <conbody>
  </conbody> 
  <concept id="concept_7A3F40D0B45D4C2D9BD4B58A1E01EEA0"> 
	 <title>Keywords and the &lt;keyword&gt; element </title> 
	 <shortdesc>The DITA Release 1.1 Architectural Specification defines
		keywords as "Terms from a controlled or uncontrolled subject vocabulary that
		apply to the topic." This definition provides some context in that it specifies
		that keywords apply to topics, but it doesn't help us determine what words to
		designate as keywords. 
	 </shortdesc> 
	 <conbody> 
		<p>The way to specify keywords in DITA is to use the &lt;keyword&gt;
		  element. "The &lt;keyword&gt; 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 &lt;keyword&gt; element is a generic element that is designed to
		  easily allow specialization. For example, the &lt;apiname&gt;, &lt;kwd&gt;,
		  &lt;option&gt;, &lt;parmname&gt;, &lt;cmdname&gt;, &lt;msgnum&gt;,
		  &lt;varname&gt; &lt;shortcut&gt;, &lt;wintitle&gt;, and &lt;shape&gt; elements
		  are all specializations of the &lt;keyword&gt; element. 
		</p> 
		<p>What do all of these elements have in common? They are elements
		  designed to capture text "that has a unique or key-like value"<fn>DITA Release
			 1.1 Language Specification , page 71</fn> Text with a unique value describes
		  text with a specific purpose, and for which you may want to attach semantic
		  value. For example, if you consistently apply the &lt;wintitle&gt; element for
		  the names of windows in the graphical user interface, you can process the
		  &lt;wintitle&gt; 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 &lt;wintitle&gt; elements upon processing.
		</p> 
	 </conbody> 
  </concept> 
  <concept id="concept_E62F91C620AE4C3D876E5B4D87FC7EF2"> 
	 <title>Why to use keywords </title> 
	 <shortdesc>The ability to control output processing for specific types of
		text is one the main reasons to use the &lt;keyword&gt; 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 &lt;keyword&gt; and &lt;indexterm&gt; elements
		  in the Web page metadata. Web metadata is important because it supports
		  search/retrieval. 
		</p> 
	 </conbody> 
  </concept> 
  <concept id="concept_9A141EBF45E04797BFEBF93FE08482BE"> 
	 <title>Where to use keywords </title> 
	 <shortdesc>You can include keywords in different places in DITA topics.
		This ability is useful because it gives you flexibility in applying the
		keywords; however, you need to consider where the keywords are appropriate. 
	 </shortdesc> 
	 <conbody> 
		<p>If you have a word or phrase to which you want to apply a semantic
		  identification, simply make any inline text a keyword by including the text
		  within the &lt;keyword&gt; element. The following example shows how to make
		  DITA a keyword in a sentence from DITA XML.org.
		  <codeblock>&lt;p&gt;&lt;keyword&gt;DITA&lt;/keyword&gt; builds content reuse into the authoring process, defining an 
XML architecture for designing, writing, managing, and publishing many kinds of information in print and on 
the Web.&lt;/p&gt;
</codeblock> 
		</p> 
		<p>You can also specify keywords in the prolog of a topic, which implies
		  that the keyword applies to the full topic AND it will apply to the full topic
		  in any context. The following example shows the XML markup:
		  <codeblock>&lt;prolog&gt;&lt;metadata&gt;
&lt;keywords&gt;&lt;keyword&gt;Whitepaper&lt;/keyword&gt;&lt;/keywords&gt;
&lt;/metadata&gt;&lt;/prolog&gt;
</codeblock>
		</p> 
		<note>You insert the &lt;prolog&gt; element between the closing
		  &lt;shortdesc&gt; tag and the opening tag for the topic body element.
		</note> 
		<p>If a keyword applies to a topic, but only in a specific context, you
		  can specify the keywords in the DITA map. The following example shows the XML
		  markup for specifying a keyword for a topic in a map:
		  <codeblock>&lt;topicref href="Topic_a.xml"&gt;
&lt;topicmeta&gt;&lt;keywords&gt;&lt;keyword&gt;XML Whitepapers&lt;/keyword&gt;&lt;/keywords&gt;&lt;/topicmeta&gt;
&lt;/topicref&gt;
</codeblock> 
		</p> 
	 </conbody> 
  </concept> 
  <concept id="concept_83826A78D62A4A4582B32417BB623B48"> 
	 <title>When to use keywords </title> 
	 <shortdesc>There are several DITA elements that seem to serve the same or
		similar purposes. For example, when do you specify a word as an index term,
		term, phrase, or keyword? 
	 </shortdesc> 
	 <conbody> 
		<section id="section_71D4329238A243F896CA3623239D2699">
		  <title>&lt;indexterm&gt; or &lt;keyword&gt;</title>
		  <p>Although the DITA OT processes &lt;keyword&gt; and &lt;indexterm&gt;
			 elements the same way for Web content, it provides additional processing for
			 &lt;indexterm&gt; elements and compiles them into an alphabetized index for
			 print, help, or other medium that includes an index. In addition, unlike
			 &lt;keyword&gt; elements, &lt;indexterm&gt; elements do not appear in output
			 text. To illustrate the difference in the output, the example shows the
			 generated text with "DITA" as a keyword.
		  <table id="table_DCD1505C4CA2484C8755A0D360DAC133">
			 <tgroup cols="1"><colspec colnum="1" colname="col1" colwidth="*"/>
				  <tbody>
					 <row>
						<entry colname="col1">DITA builds content reuse into the
						  authoring process, defining an XML architecture for designing, writing,
						  managing, and publishing many kinds of information in print and on the Web. 
						</entry>
					 </row>
				  </tbody>
			 </tgroup>
		  </table> 
		  </p>
		  <p>In contrast, the following text shows the generated text with 
			 <codeph>&lt;indexterm&gt;DITA&lt;/indexterm&gt;</codeph>:
		  <table id="table_017760E7962B44E88CE95529EFA22DF1">
			 <tgroup cols="1"><colspec colnum="1" colname="col1" colwidth="*"/>
				  <tbody>
					 <row>
						<entry colname="col1">builds content reuse into the authoring
						  process, defining an XML architecture for designing, writing, managing, and
						  publishing many kinds of information in print and on the Web. 
						</entry>
					 </row>
				  </tbody>
			 </tgroup>
		  </table>
		  </p>
		  <p>In the second example, the word "DITA" is missing. To have a word or
			 phrase appear in the text as well as in the index, you must apply both
			 &lt;indexterm&gt; and &lt;keyword&gt;. 
			 <codeblock>&lt;indexterm&gt;DITA&lt;/indexterm&gt;&lt;keyword&gt;DITA&lt;/keyword&gt; builds content reuse
into the authoring process, defining an XML architecture for designing, writing, managing, and 
publishing many kinds of information in print and on the Web.
</codeblock>
		  </p>
		  <p>Although it looks redundant when you view the XML markup, the output
			 from the above example generates the text with "DITA" as the keyword and
			 includes "DITA" in the index.
		  </p> 
		</section> 
		<section id="section_22A8E9C9397D47EF8BC58F6B507E9953">
		  <title>&lt;term&gt; or &lt;keyword&gt;?</title>
		  <p> The important distinction to note between a keyword and a term is
			 the purpose of the text. If you are defining a term in the text, then use the
			 &lt;term&gt; element rather than &lt;keyword&gt; for the inline element. The
			 &lt;term&gt; element identifies words that may have or require extended
			 definitions or explanations." 
			 <fn>DITA Release 1.1 Language Specification, page 204 
			 </fn> If you consistently apply the &lt;term&gt; element when you are
			 defining words or phrases, you can easily format the text according to your
			 corporate style, such as formatting terms in text with italics.
		  </p> 
		</section> 
		<section id="section_C7DBE4A9C3014B3F9F865A5CEF75799C">
		  <title>&lt;phrase&gt; or &lt;keyword&gt;?</title>
		  <p>The &lt;phrase&gt; and &lt;keyword&gt; elements are valid in almost
			 all of the same places in DITA topics, but they are not interchangeable. The
			 primary difference is the purpose of the elements. If you want to classify text
			 as semantically important, use the &lt;keyword&gt; element. If you simply want
			 to encapsulate text in a generic element for reuse or conditional processing,
			 then use the &lt;phrase&gt; element. 
		  </p>
		  <p>For example, if you want to reuse a word, but it does not have
			 semantic meaning, you can apply the &lt;phrase&gt; element, assign an ID to the
			 &lt;phrase&gt; element, and then reference the ID using the conref attribute.
			 Granted, you can achieve the same outcome with the &lt;keyword&gt; element, but
			 the DITA OT also processes the &lt;keyword&gt; element for the Web metadata. 
		  </p>
		  <p>Another point to note is that the default .css that ships with the
			 DITA OT applies the bold style to keywords. Of course, you can override this
			 formatting with your own .css.
		  </p>
		</section> 
	 </conbody> 
  </concept> 
  <concept id="concept_D2D8A0776059431D95FD808096619977"> 
	 <title>Summary</title> 
	 <shortdesc>The rule when applying elements is to apply the element that
		provides the minimum processing that you need. If you do not need the semantic
		processing that the &lt;keyword&gt; element provides, do not use it; rather,
		use the element that provides the appropriate processing power and output.
	 </shortdesc> 
	 <conbody> 
		<p>If you are generating XHTML for Web output or need to identify text
		  with semantic distinction, then the &lt;keyword&gt; element provides value. In
		  many other cases, you can achieve the desired resulting processing and output
		  with other elements.
		</p> 
	 </conbody> 
  </concept> 
</concept> <?Pub *0000009820 0?>
<?xml version="1.0"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<!-- Created with XMetaL (http://www.xmetal.com) -->
<concept id="concept_A87B5F22D1584B75B614A16E7B54DDC4"> 
  <title>Choosing the correct DITA element</title> 
  <shortdesc>Although it is clear how to appropriately use the majority of DITA
	 elements, there are several elements that are similar or related, which causes
	 confusion for many content authors. To help authors choose the correct element
	 for the context, DITA XML.org will present a series of articles to clarify best
	 practices for using some of the most frequently-questioned elements. 
  </shortdesc> 
  <conbody>
	 <p>The proposed list of elements to address includes:
	 <ul id="ul_18D4D61BC8E54C30A6EDEE69F3A0E3D9">
		<li id="li_4D683CAA2F5C4E34A50B426D092319CB">&lt;keyword&gt;
		</li>
		<li id="li_3833CD5DC4C740879737E11AF44749EC">&lt;indexterm&gt; and new
		  index elements in DITA 1.1
		</li>
		<li id="li_C3551840649B442A886642C9634802D3">&lt;term&gt; and glossaries
		</li>
		<li id="li_F71D62AC0E944560A497B84551F253F5">&lt;phrase&gt;
		</li>
		<li id="li_3809818A0FF243B69A7FF77DB02C9B9A">&lt;data&gt;
		</li>
	 </ul>
	 </p>
	 <p>The current soapbox article, "Keywords: why, where and when to use
		them", starts the series. 
	 </p>
  </conbody> 
</concept>

Title: Keywords: why, where and when to use them

Keywords: why, where and when to use them

According to Wikipedia, a keyword "is a word or concept with special significance." This definition is a very broad; it emcompasses a wide range of uses. This article explains what keywords are in DITA and proposes guidance for keyword usage.

Keywords and the <keyword> element

The DITA Release 1.1 Architectural Specification defines keywords as "Terms from a controlled or uncontrolled subject vocabulary that apply to the topic." This definition provides some context in that it specifies that keywords apply to topics, but it doesn't help us determine what words to designate as keywords.

The way to specify keywords in DITA is to use the <keyword> element. "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."¹

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.

What do all of these elements have in common? They are elements designed to capture text "that has a unique or key-like value"² Text with a unique value describes text with a specific purpose, and for which you may want to attach semantic value. 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.

Why to use keywords

The ability to control output processing for specific types of text is one the main reasons to use the <keyword> element.

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.

Where to use keywords

You can include keywords in different places in DITA topics. This ability is useful because it gives you flexibility in applying the keywords; however, you need to consider where the keywords are appropriate.

If you have a word or phrase to which you want to apply a semantic identification, simply make any inline text a keyword by including the text within the <keyword> element. The following example shows how to make DITA a keyword in a sentence from DITA XML.org.

<p><keyword>DITA</keyword> builds content reuse into the authoring process, defining an 
XML architecture for designing, writing, managing, and publishing many kinds of information in print and on 
the Web.</p>

You can also specify keywords in the prolog of a topic, which implies that the keyword applies to the full topic AND it will apply to the full topic in any context. The following example shows the XML markup:

<prolog><metadata>
<keywords><keyword>Whitepaper</keyword></keywords>
</metadata></prolog>

Note: You insert the <prolog> element between the closing <shortdesc> tag and the opening tag for the topic body element.

If a keyword applies to a topic, but only in a specific context, you can specify the keywords in the DITA map. The following example shows the XML markup for specifying a keyword for a topic in a map:

<topicref href="Topic_a.xml">
<topicmeta><keywords><keyword>XML Whitepapers</keyword></keywords></topicmeta>
</topicref>

When to use keywords

There are several DITA elements that seem to serve the same or similar purposes. For example, when do you specify a word as an index term, term, phrase, or keyword?

<indexterm> or <keyword>

Although the DITA OT processes <keyword> and <indexterm> elements the same way for Web content, it provides additional processing for <indexterm> elements and compiles them into an alphabetized index for print, help, or other medium that includes an index. In addition, unlike <keyword> elements, <indexterm> elements do not appear in output text. To illustrate the difference in the output, the example shows the generated text with "DITA" as a keyword.

DITA builds content reuse into the authoring process, defining an XML architecture for designing, writing, managing, and publishing many kinds of information in print and on the Web.

In contrast, the following text shows the generated text with <indexterm>DITA</indexterm>:

builds content reuse into the authoring process, defining an XML architecture for designing, writing, managing, and publishing many kinds of information in print and on the Web.

In the second example, the word "DITA" is missing. To have a word or phrase appear in the text as well as in the index, you must apply both <indexterm> and <keyword>.

<indexterm>DITA</indexterm><keyword>DITA</keyword> builds content reuse
into the authoring process, defining an XML architecture for designing, writing, managing, and 
publishing many kinds of information in print and on the Web.

Although it looks redundant when you view the XML markup, the output from the above example generates the text with "DITA" as the keyword and includes "DITA" in the index.

<term> or <keyword>?

The important distinction to note between a keyword and a term is the purpose of the text. If you are defining a term in the text, then use the <term> element rather than <keyword> for the inline element. The <term> element identifies words that may have or require extended definitions or explanations." ³ If you consistently apply the <term> element when you are defining words or phrases, you can easily format the text according to your corporate style, such as formatting terms in text with italics.

<phrase> or <keyword>?

The <phrase> and <keyword> elements are valid in almost all of the same places in DITA topics, but they are not interchangeable. The primary difference is the purpose of the elements. If you want to classify text as semantically important, use the <keyword> element. If you simply want to encapsulate text in a generic element for reuse or conditional processing, then use the <phrase> element.

For example, if you want to reuse a word, but it does not have semantic meaning, you can apply the <phrase> element, assign an ID to the <phrase> element, and then reference the ID using the conref attribute. Granted, you can achieve the same outcome with the <keyword> element, but the DITA OT also processes the <keyword> element for the Web metadata.

Another point to note is that the default .css that ships with the DITA OT applies the bold style to keywords. Of course, you can override this formatting with your own .css.

Summary

The rule when applying elements is to apply the element that provides the minimum processing that you need. If you do not need the semantic processing that the <keyword> element provides, do not use it; rather, use the element that provides the appropriate processing power and output.

If you are generating XHTML for Web output or need to identify text with semantic distinction, then the <keyword> element provides value. In many other cases, you can achieve the desired resulting processing and output with other elements.

DITA Release 1.1 Language Specification, page 71

DITA Release 1.1 Language Specification , page 71

DITA Release 1.1 Language Specification, page 204

Title: Choosing the correct DITA element

Choosing the correct DITA element

Although it is clear how to appropriately use the majority of DITA elements, there are several elements that are similar or related, which causes confusion for many content authors. To help authors choose the correct element for the context, DITA XML.org will present a series of articles to clarify best practices for using some of the most frequently-questioned elements.

The proposed list of elements to address includes:

• <keyword>
• <indexterm> and new index elements in DITA 1.1
• <term> and glossaries
• <phrase>
• <data>

The current soapbox article, "Keywords: why, where and when to use them", starts the series.