dita message

Subject: Examples in the DITA specification

From: Kristen James Eberlein <kris@eberleinconsulting.com>
To: DITA TC <dita@lists.oasis-open.org>
Date: Mon, 14 Oct 2019 12:41:05 -0400

This is to close out an existing action item that Tom Magliery and I had.

There are four categories of examples in the DITA specification:

1) Examples in the element reference topics

This is a standard section of each element reference topic.

2) Example topics in the architectural part of the DITA spec

These exist for the more complicated DITA features, such as keys, key scopes, subject scheme maps, DITAVALref.
Some of these topics use the <example> element; others do not. (Do any of the <example> elements contain <title>?)
Examples:

3) Example sections within the architectural topics

Examples:

http://docs.oasis-open.org/dita/dita/v1.3/errata02/os/complete/part1-base/archSpec/base/cascading-of-attributes-from-map-to-map.html#cascading-of-attributes-from-map-to-map

4) Examples embedded within topics in the architectural part of the DITA spec

I see two patterns:

Content tagged with otherprops="examples", and might be good candidates for using <example> in DITA 2.0. (They do not use the <example> element.) They are not labeled with "Example", and so are not immediately visible unless you are working with the DITA source.
Hard coded with <b>Example</b>

Examples:

Hard-coded with example: http://docs.oasis-open.org/dita/dita/v1.3/errata02/os/complete/part1-base/archSpec/base/dita-terminology.html#terminology See "Linking and addressing terms"

I suggest that spec editors add an items for standardizing examples in the DITA spec to their backlog: https://wiki.oasis-open.org/dita/editorialBacklogDITA2.0

--
Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)