[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
RE: [dita-fa-edboard] Traffic Report for DITA XML.org site
- From: "JoAnn Hackos" <joann.hackos@comtech-serv.com>
- To: "Scott Prentice" <sp@leximation.com>,"Amber Swope" <amber.swope@xmetal.com>
- Date: Tue, 8 May 2007 06:44:08 -0600
|Amber,
I'm traveling now but have the article with me.
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: Scott Prentice [mailto:sp@leximation.com]
Sent: Monday, May 07, 2007 10:14 AM
To: Amber Swope
Cc: dita-fa-edboard@lists.xml.org
Subject: Re: [dita-fa-edboard] Traffic Report for DITA XML.org site
Hi Amber...
I think this is a great article .. it certainly clarified things a bit
for me! :)
I think the use of <codeblock> for examples works fine (at least in
FrameMaker).
Yes .. it is my understanding that the more robust search engines do not
use metadata content in any significant way (or at least don't use it in
a way that it was intended), because of the widespread abuse of this
data. As far as I know it's not detrimental to include metadata, unless
it's obvious that you're using it in a way that would appear to attempt
to artificially increase hits to your site. If this is the case, those
pages may be ranked lower or excluded from the search.
I think there's a word missing from the first sentence of the "<phrase>
or <keyword>?" topic .. should that sentence end with .. "... however,
they are not interchangeable." .. with "however" (or some similar
construct) added?
...scott
Amber Swope wrote:
>
> 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
>
> ----------------------------------------------------------------------
> --
>
> <?xml version="1.0"?>
> <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
> "concept.dtd">
> <!-- Created with XMetaL (http://www.xmetal.com) --> <concept
> id="concept_B53B5D0F8C8848978E10D769D3BA5696">
> <title>Keywords: where, why and when to use them</title>
>
> <shortdesc>
> According to Wikipedia, a keyword "is a word or concept with special
> significance." This is a very broad definition that 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></keywords></met
> adata></prolog><conbody> </conbody><concept
> id="concept_7A3F40D0B45D4C2D9BD4B58A1E01EEA0"><title>Keywords and the
> <keyword> 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 <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."<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>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> This means that the text falls into a category of text
> with a specific purpose, and for which you may want to attach semantic
> value. If you consistently apply the <wintitle> element for the
> names of windows in the graphical user interface, then you can process
> the <wintitle> element differently than 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 to
> 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 is that it enables styles and
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 is useful in that you have flexibility for
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 semantic identification, then you simply make any in-line
> 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 <xref href="http://dita.xml.org"; scope="external"
format="html"><?xm-replace_text
http://dita.xml.org?></xref>:<codeblock><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>
</codeblock>
> </p><p>You can also specify keywords in the prolog for 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><prolog><metadata>
> <keywords><keyword>Whitepaper</keyword></keywords
> >
> </metadata></prolog>
> </codeblock></p><note>You can only insert the <prolog> element
> between the closing <shortdesc> 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><topicref href="Topic_a.xml">
> <topicmeta><keywords><keyword>XML
> Whitepapers</keyword></keywords></topicmeta>
> </topicref>
> </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><indexterm>
> or <keyword></title><p>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. In addition,
unlike <keyword> elements, <indexterm> elements do not
appear in output text. To see the difference in the output, the first
example shows the generated text with "DITA" as a
keyword.<codeblock><b>DITA</b> 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>In contrast, the following text shows the generated text
with
> <codeph><indexterm>DITA</indexterm></codeph>:<lines>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.
>
> </lines></p><p>To have a word or phrase appear in the text as well as
> in the index, you must apply both elements to the text.
>
<codeblock><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.
> </codeblock></p><p>Although it looks redundant when you view the XML
> tags, 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><term> or
<keyword>?</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 <term>
element rather than <keyword> for the in-line element.
>
> The <term> 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 <term> element when you defining words or
> phrases, you can easily format the text according to your corporate
> style, such as to format terms in text with italics.</p>
> </section><section
> id="section_C7DBE4A9C3014B3F9F865A5CEF75799C"><title><phrase> or
> <keyword>?</title><p>The <phrase> and <keyword>
> elements are valid in almost all of the same places in DITA topics,
> they are not interchangeable. The primary difference is the purpose of
> the elements. If you want to classify text as being semantically
> important, then 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. </p><p>For example,
> if you want to reuse a word, but it does not have semantic meaning,
> then you can apply the <phrase> element, assign an ID to the
> <phrase> element, and then reference the ID using the conref
> attribute in many of the DITA elements. Granted, you can accomplish
> the same outcome with the <keyword> element, but the DITA OT
> also processes the <keyword> 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 with your own
> .css.</p></section></conbody></concept><concept
> id="concept_D2D8A0776059431D95FD808096619977"><title>Summary</title>
> <shortdesc>The rule of thumb 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.</shortdesc><conbody><p>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 using other
> elements.</p></conbody></concept></concept>
>
> ----------------------------------------------------------------------
> --
>
> ---------------------------------------------------------------------
> 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]
