Next in thread →
Next in month →
Re: [dita] Guidelines for element reference topics moving forward
Amber, we are not going to include the content models in the
spec. That's a decision we made quite a long time ago.
There is no good way to generate them, and they've always been
full of errors. They also are not normative.
If we can find a better way to generate them, we'll publish them
as an axillary document.
Robert and I will try to provide examples of 1.3 content, phase 1
content, and phase 2 content as soon as we can.
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)
On 7/3/2018 3:09 PM, Amber Swope wrote:
Hi
there,
Â
My
apologies if I missed the discussion, but where will the
content model information be located? The guidance in this
email indicates that it doesnât belong in the usage section,
which seems correct; However, this information is vital to
information architects and needs to be included somewhere in
the spec.
Â
Also,
can you please provide a full example topic, such as for
<navtitle>, so that we can see where you expect
information to move? It would be great to see examples of
the same content as DITA 1.3, phase 1 and phase 2.
Â
Thanks,
Amber
Â
From:
[mailto:]
On Behalf Of Kristen James Eberlein
Sent: Monday, July 2, 2018 3:56 PM
To: DITA TC
Subject: [dita] Guidelines for element reference
topics moving forward
Â
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
Next in thread →
Next in month →