Re: [dita-techcomm] Revised proposal for separating Technical Content from the core specificaiton

["Robert D Anderson" <robander@us.ibm.com>]

Hi Bob,

I think this looks better.

I'm afraid I'll be missing the call today, so sending a couple notes in advance:

- For the grammar file section - I don't think we should really even mention RNG, DTD, or Schema. Whatever we do with those will match what the main spec does. Instead, I'd point out that Tech Comm grammar files will be part of this separate deliverable. We should also point out that it has the same dependency issue as the spec content -- how do we bundle the core grammar files, which are required to make the TC grammar files work?

- Overall usability -- I probably wouldn't lead with "it will be diminished". I think the most we can say now is that this is possible -- it might be diminished, but whether that happens and by how much will depend on the eventual delivery mechanism.

Regards, Robert D. Anderson DITA-OT lead and Co-editor DITA 1.3 specification, Digital Services Group
E-mail: robander@us.ibm.com Digital Services Group
11501 BURNET RD,, TX, 78758-3400, AUSTIN, USA

Bob Thomas ---04/02/2017 04:42:15 PM---Here is the latest revision. It is by no means complete, but it may be far enough along to take to t

From: Bob Thomas <bob.thomas@tagsmiths.com>
To: DITA Tech Comm SC <dita-techcomm@lists.oasis-open.org>
Date: 04/02/2017 04:42 PM
Subject: [dita-techcomm] Revised proposal for separating Technical Content from the core specificaiton
Sent by: <dita-techcomm@lists.oasis-open.org>

---

Here is the latest revision. It is by no means complete, but it may be far enough along to take to the DITA TC for feedback.

DITA 2.0 proposed feature #nn—Technical content work product

The technical content specializations will be moved to their own work product when DITA 2.0 is released

Date and version information

Completed

Champion

Bob Thomas
Previous versions

Discussion

Original requirement or use case

Use case: Adding a new information type

Suppose that the DITA TC approves the addition of a new technical content information type for the semantic representation of process information during a time when there is no compelling reason to enhance DITA 2.0. The process information type could be added to the technical content work product without waiting for an update to the core DITA specification. This would allow the DITA to be more responsive to the needs of the technical content community.

Use case: Adding a new element domain

Suppose that the DITA TC approves the addition of a new element domain that models the semantics of documenting web application programming. The same benefits present in the new information type use case also apply here.

Proposed solution: Technical content specification

The Technical content specification would be contain the following sections:
Overview
Architectural specification. The starting point for this would come from the DITA 1.3 specification, section 2.7 Technical content specialization.
Language specification. The starting point for this would come from the DITA 1.3 specification, section 3.10 Technical content elements.

The technical content work product would not include content models. Readers would need to examine the RNG grammar files which are normative.

Attribute descriptions would:

Define any attributes that are unique to an element or that have an overloaded meaning that differs from that of its specialization ancestors
List the attribute groups that are used

Problem: information dependencies upon the core specification

The technical content specification depends upon the following information in the core specification:

• Attribute definitions. Most of the attributes available in the technical content elements are defined in the core specification.
• Core elements. Most of the elements in the technical content models come from the core specification.
• DITA architectural rules. As a DITA vocabulary, technical content is subject to the DITA architectural specifications that are defined in the core.
These dependencies present a challenge when technical content is delivered as a separate work product, particularly with regard to attribute definitions.

Attributes on the <step> element.

The following attributes are available on this element: Universal attribute group (with a narrowed definition of @importance , given below) and @outputclass. …

Dealing with attribute definitions

Here are some approaches for dealing with references to attribute definitions:

Cross-publication linking

Implement some sort of cross-publication linking scheme from the technical content document pointing to the appropriate places in the core specification.
Unlinked references
Mention attribute groups and specific attributes without linking. The reader would be responsible for chasing down the information in the core specification.
Appendix that contains dependencies
Create an appendix that reuses content from the core specification (section 3.11) to provide link targets for attribute definitions. Links from section 3.11 into the rest of the core specification would have to either be pruned or deactivated.
Proposed solution: Technical content grammar files

The following would occur:
The rng/technicalContent and dtd/technicalContent grammar files would move to the technical content work product
The OASIS catalog declarations for those grammar files would move with the grammar files

There are no plans to migrate schema/technicalContent or schema-url/technicalContent. Those files would simply be removed from the DITA 2.0 grammar files structure.

Benefits

Moving the technical content specializations into a separate work product has the following benefits:

• The core DITA specification would be easier to maintain
• It would no longer be necessary to have multiple editions of the DITA specification
• Technical content grammar changes and additions would no longer need to be synchronized with updates to the DITA base
• It would become clearer that DITA is more than just the technical content specializations
Technical requirements

The technical content specification must:
Cover everything that is in sections 2.7 and 3.10 in the 1.3 specification.
Include all relevant changes introduced by the DITA 2.0 core specification.
Include all DITA 2.0 enhancements from the Technical Communications subcommittee that have been approved by the DITA TC.

The DITA Technical Communications subcommittee would be responsible for maintaining and revision the technical content work product given that all changes would be subject to approval by the DITA TC.

Backwards compatibility

There are no backward compatibility issues associated with this proposal.

Costs

Implementing this feature would have the following consequences:

Processing impact

None.
Overall usability
Usability would be somewhat diminished because the technical content specification would have to be used in conjunction with the core specification to understand the complete context within which the technical content work product could be used.
Vendors of tools
Tools that include grammar files would need to include an package
DITA community-at-large
Information architects would need to be aware that technical content has moved into its own work product.

-- 
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)