Summary: Status of review of the DITA2.0/LwDITA intersection topics

[Kristen James Eberlein <kris@eberleinconsulting.com>]

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:

1. 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.
   
2. Examples: Lots of comments here
1. 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.
2. 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.
3. 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 ...

--
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?