[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: 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:
Short description Guidance for reorganization 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
Usage information What 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:
Examples <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 Guidance for reorganization 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:
Processing expectations What this section contains 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 Guidance for
reorganization Specialization hierarchy
What this
section contains Phase one: Rewrite this section using the format indicated in "Examples" below. Examples:
Example What this section
contains
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:
--
Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 622-1501; kriseberlein (skype) |
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]