OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Re: [dita] Guidelines for element reference topics moving forward


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:
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 <kris@eberleinconsulting.com> 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 (bob.thomas@tagsmiths.com) or Skype
Time zone: Mountain (GMT-7)




[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]