During today's TC discussion about the specialization hierarchy section, there was some concern about omitting the hierarchy from the spec. It occurred to me that the two examples in that section could easily be adapted to provide that information:
The <taskbody> element is specialized from <body>. Its specialization hierarchy is declared in the task module as - topic/body task/taskbody
The <b> element is specialized from <ph>. Its specialization hierarchy is declared in the highlighting-domain module as + topic/ph hi-d/b
While I don't particularly like having a dependency on the contents of the respective modules, that dependency already exists for the plain language portion of the examples. Namely, if the @class changes in the module, then the plain language will have to change as well.
Best regards,
Bob
On Mon, Jul 2, 2018 at 4:55 PM, Kristen James Eberlein <> wrote:
OK, here is a summary of what Robert, Carlos, and I came up with
as we reviewed and edited topics that exist in both LwDITA and
DITA 2.0. Obviously this will be a living document that will be
refined as more and more editorial work happens on the following
works products:
DITA 2.0 spec
LwDITA spec
DITA for ? 2.0 spec (replacement for DITA for Technical
content)
Learning and Training 2.0 spec
Short description
A natural language description of what something actually IS.
Guidance for reorganization
Phase one: Move content into other appropriate sections.
Phase two: Rewrite the shortdesc to use natural language. Ensure
that shortdesc for topics that exist in both DITA 2.0 and LwDITA
are referenced from the appropriate topic using conkeyref.
Examples
<navtitle>
DITA 1.3:
The
navigation title (<navtitle>)
element is one of a set of alternate titles that can be
included inside the <titlealts> element.
This navigation title might differ
from the first level heading that shows in the main
browser window. Use <navtitle> when
the actual title of the topic isn't appropriate for use in
a table of contents, navigation pane, or online content
(for example, because the actual title is too long). Beginning
with DITA 1.2, the <navtitle> element
is also available in the <topicmeta> element
in a <topicref> in
a map, and its use is preferred over the <topicref> element's @navtitle attribute.
DITA 2.0 draft:
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.
<shortdesc>
DITA 1.3:
The <shortdesc> element
provides a short description of the topic. The short
description, which represents the purpose or theme of the
topic, is also intended to be used as a link preview and
for search results. The element can occur both in topics
and maps.
DITA
2.0 draft:
A
short description describes the purpose or main point of a
topic.
Usage information
What this section contains
This section contains ...
Guidance for reorganization
Phase one: As we reorganized topics into the new format, this was
a catch-all section for material that did not clearly belong in
other sections.
Phase two: When we moved into a editorial mode, often we deleted
the entire section. This section should not contain the following
information:
A narrative description or elaboration of the content model
Tutorial information
Best practices for authoring in DITA
Examples
(DITA 2.0 draft, after 1st and 2nd pass) "The following list
outlines common uses of the <desc> element:
<table> and <fig>
Provides more information than can be contained in the title.
<xref> and <link>
Provides a description of the target.
<object>
Provides alternate content to use when the context does not permit
displaying the object.
Formatting expectations
What this section contains
This section contains information/guidelines about typical
rendering of elements.g is left up to implementations, so there
should not be any normative text in this section. This
section is meant to include formatting guidelines, not rules.
Guidance for reorganization
Phase one: Move any content into this section that is about
formatting.
Phase two: Rewrite the section. Include a words like "typically."
Do not state "Although rendering is left up to implementations,"
since we will have a (reuse) topic that clearly states that and
can be used in all specs.
Examples
DITA 1.3 spec shortdesc: "When a DITA topic is rendered, numbers
and alpha characters are typically displayed with list items in
ordered lists, while bullets and dashes are typically displayed
with list items in unordered lists."
(DITA 2.0 draft): Processors typically use the following
conventions for displaying the contents of <li> elements:
In ordered lists, list items are indicated by numbers or
alphabetical characters.
In unordered lists, list items are indicated by bullets or
dashes.
Processing expectations
What this section contains
This section contains information about how processors should
handle content.
Guidance for reorganization
Phase one: Move any content into this section that is about what a
processor does with content. Any normative statements must
go here.
Phase two: Rewrite and edit the section. Normative statements
should be written so that they make sense when reused outside of the
topic.
Examples
(DITA 2.0 draft, after 1st pass) "Processors SHOULD render the
content of the <shortdesc> element as the initial paragraph of
the topic.
When processors generate link previews that are based on the map
context, they SHOULD use the content of the <shortdesc> that
is located in the map rather than the <shortdesc> that is
located in the DITA topic. However, processors SHOULD use the
content of the <shortdesc> element in the DITA topic when they
render the topic itself, unless the @copy-to attribute is specified
on the topic reference to the element."
Attributes
What this section
contains
This section contains information about attributes.
Guidance for
reorganization
Phase one: Move any normative statements into the "Processing
expectations" section; be sure and indicate what attribute
they referred to originally.
Phase two: Rewrite and edit the section. Normative
statements should be written so that they make sense when
reused outside of the topic.
Specialization hierarchy
What this
section contains
This section contains information about the specialization
base for an element. This section should not be
present if the element is part of the DITA base.
Guidance for
reorganization
Phase one: Rewrite this section using the format indicated in
"Examples" below.
Examples:
The <taskbody> element is specialized from <body>.
It is defined in the task module
The <b> element is specialized from <ph>. It is
defined in the highlighting-domain module.
Example
What this section
contains
This section contains about how an element can be used.
Guidance for
reorganization
Phase one: Restructure the section using the following
principals:
If the section
includes more than one example, group each within a
<fig> tag that contains a descriptive <title>.
Add at least one
introductory paragraph (although good text might need to
wait for the 2nd or 3rd phase.)
Ensure that the
section has id="examples"
If there are
multiple examples, the title of the section should be
"Examples".
Phase two or three:
Rewrite the section to ensure that it contains a good, solid,
and realistic examples.
We are really
working on developing good guidelines for these examples, but
we are not there yet. Here are some of our working notes:
If we struggle to write introductory text, maybe the example
is too simplistic. Should use a variety of fields and industry
domains: hardware, software, manufacturing, marketing, etc.
Use highlighting judiciously within a code sample, since it
impedes our ability to reuse the code samples. Do use
bold highlighting when a particular element needs to be
emphasized and otherwise might not stand out.
Reused examples should be stored in a reuse topic.
Code samples should use two-space indentation.
--
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)
---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail. Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
--
Bob Thomas
+1 720 201 8260
Skype: bob.thomas.colorado
Instant messaging: Gmail chat () or Skype
Time zone: Mountain (GMT-7)
