← Prev in month
← Prev in thread
Next in thread →
Next in month →
Updated summary: Status of review of the DITA2.0/LwDITA intersection topics
Remember the DITAweb review that was run in October 2018? I've
spent about 20 hours this work going through the DITAweb review,
resolving what I can, and compiling a list of items that still
need resolution.
Here's a summary:
Short descriptions: 10 topics need discussion. I've
set up a meeting for noon - 1 PM ET on Monday, 28 January
2019; ping me if you want an invitation. Currently, the
attendees will be me, Robert, Carlos, and Alan. Attached is an
HTML summary of the comments that we'll begin with.
UPDATE: Only three topics need
attention: keydef, map, and topicref.
Attributes: Need editing and standardization of
format (for example, should each entry begin with a verb ...)
Examples: Lots of comments here
We need to standardize the introductory paragraphs that
precede the code blocks. We need to decide what is the best
approach, and whether we will identify a few patterns that
can be used, or a single pattern.
Concern that some of the examples are too US-centric or
inaccessible to ESL readers, for example, a reference to
Rotten Tomatoes and "How to purchase SuperWidgets from the
warehouse." We need to enhance our guidelines for example.
Suggestions of multiple additional examples. We need to
review our existing guidelines for examples and see what
they say. My gut sense is that many of the proposed examples
are too complex and do not belong in element reference
topics.
Two topics need to be reworked and reviewed: <fn> and
<ph>. Ughhh ... UPDATE:
COMPLETED.
--
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)
Title: Short descriptions
Short descriptions
This topics contains comments about short descriptions that were harvested from the
October 2018 DITAweb review. That review focused on element reference topics for elements
that exist both in DITA and LwDITA.
<alt>
(Original) Alternate text is a textual description of an image that can be
read or displayed in place of the image. This is commonly used to create
text alternatives for readers or systems that cannot view the original
image.
(Stan): Alternate text is a textual description of an image. Readers or
systems that cannot view the original image can read or display this
alternate text.
(Alan): This shortdesc is still tortured. Is "textual" a word? How about
"Alternate text specifies a text description of an image. It is commonly
rendered by systems that cannot display the image, or in situations where
text is preferred or required.".
(Kris): Yes, "textual" is a common adjective. Think of textual analysis,
textual criticism, and Derrida's comment that the end of the world would be
"fabulously textual". I like Stan's suggestion.
<data>
(Original) Data is a generic component that represents metadata within a
DITA topic or map. Complex metadata is represented by nested data
structures.
(Carlos) Shortdesc seems complicated with many instances of the words "data"
and "metadata." Propose something like "a generic component for metadata."
Avoid mentioning DITA directly.
(Kris) Why should we avoid mentioning DITA?
(Stan) Data is a generic element that represents metadata within a DITA
topic or map. You can nest multiple <data> elements
to create complex metadata or data structures.
(Alan) Can't use "element" in shortdescs, because of non-XML
Lightweight DITA file formats. "Component" is preferred when
necessary, but even "component" can usually be avoided...
(Alan) How about something like "Data provides a container for metadata
name/value pairs, and can be nested to represent nested data structures"?
Maybe omit the "nested" clause from the shortdesc?
(Deb) Component is a term that I'm not familiar with in context of the DITA
spec. If we want to use it here, that is fine, but we need to define what we
mean. I prefer using "element" rather than component.
(Kris) Deb, we need to avoid using the word element in short
descriptions, since they will be shared with the LwDITA spec.
<desc>
(Original) A description is a statement that describes or contains
additional information about an object.
(Stan) A description is a statement that provides additional information
about an object.
(Deb) I'm concerned about using the term object in this description. Readers
might confuse this term with the DITA object<> element. The DITA
1.3 spec used element, but I think that might be too broad. I'm not sure
that I have a good suggestion.
<i>
(Original) Italic text is a way to emphasize the key points in printed text,
or when quoting a speaker, a way to show which words the speaker
stressed.
(Stan) Italic text is a way to emphasize the key points in printed text, to
indicate emphasis when quoting a speaker, or to indicate variable text.
(Deb) Italic text is used to emphasize the key points in printed text, or
when quoting a speaker, a way to show which words the speaker stressed.
(Kris) Italic text is formatting that can be used to emphasize key points in
written text or a verbal dialog.
<keydef>
(Original) The key definition convenience element provides a simple way to
define a key without making the definition itself a part of rendered
content. As with any key definition, the resource will still be rendered
when the key is referenced.
(Stan) The key definition convenience element provides a simple way to
define a key without making the definition itself a part of rendered
content. As with any key definition, the referenced resource will still be
rendered when the key is resolved.
(Deb) A key definition provides a simple way to define a key without making
the definition itself a part of rendered content. As with any key
definition, the resource will still be rendered when the key is
referenced.
<navtitle>
(Original) A navigation title provides a title for a resource. When used in
topics, it is an alternate title that is designed for situations when the
topic title is unsuitable for use in a table of contents or navigation pane.
When used in maps, a navigation title can serve as an alternate title or
simply as an aid to understanding the DITA map.
(Carlos) In LwDITA, navtitle only exists in maps (there is no navtitle in
topic). Keep short description as "A navigation title provides a title for a resource"?
(Kris) I think we'll need to do some conditional processing here, or
add this content to "Usage information." For now, I've changed the
shortdesc to "A navigation title is an alternate title for a
resource; this alternate title is optimized for situations where the
topic title is unsuitable for use in a table of contents or
navigation pane." and moved the other content into "Usage
information." Is this going to work for LwDITA?
(Stan) When added to <topicref locktitle="yes"> and <topicmeta>
elements in a map, processors use the contents of <navtitle> instead of
the topic title when they construct print TOCs and navigation TOCs. The
contents of the topic title itself are not changed.
(Kris) Too much info for a shortdesc, but we can evaluate whether
this info belongs in "Usage information." However, changes related
to Chris Nitchie's proposal about alt titles in maps might make this
obsolete.
<title>
(Original) A title is a heading or label for an object. Titles can be
associated with topics, maps, sections, examples, figures, tables, and other
structures.
(Deb) Could object be confused with the <object>
element?
<topicmeta>
(Original) Topic metadata is metadata that applies to a topic; this metadata
is defined in a map.
(Carlos) Propose a single sentence like "defines metadata that applies to a
topic when it is referenced in a map"
(Kris) That's a little imprecise, since metadata defined in the
prolog also applies to a topic when it is referenced in a map.
<topicref>
(Original) A topic reference is the mechanism for referencing a topic (or
another resource) from a DITA map. It can nest, which enables the _expression_
of navigation and table-of-content hierarchies, as well as containment
hierarchies and parent-child relationships.
(Carlos) Shortdesc makes reference to DITA map. Suggest something shorter
like " identifies and links to a topic or external content source."
(Eberlein) Why shouldn't there be a reference to a DITA map?
← Prev in month
← Prev in thread
Next in thread →
Next in month →