RE: [dita-techcomm] Review of 13102 stage 3 Release Management

[Cihak Thomas-R65612 <R65612@freescale.com>]

Hi Dave,

 

Thanks for reviewing. I changed the short description in <change-request-id> to match the description in the arch spec topic:

 

“contains an ID or other reference number used by the external system”

 

with best regards

 

Tom Cihak

Digital Networking Information Development

Freescale

512.996.5072

 

From: dita-techcomm@lists.oasis-open.org [mailto:dita-techcomm@lists.oasis-open.org] On Behalf Of Helfinstine, David
Sent: Monday, October 28, 2013 12:56 PM
To: DITA Tech Comm SC
Cc: Cihak Thomas-R65612
Subject: RE: [dita-techcomm] Review of 13102 stage 3 Release Management

 

Greetings,

 

I have finished reviewing the PDF version.

 

This looks good with the same comments as below.

 

Additional comments:

Page 3: “no processing is requested” to “with no processing requirements”

 

There is one additional area I did not understand at all. That was the “change-request-reference”. This all talks about an external tracking system. That all seems quite mysterious and wonder if this has a particular tracking system in mind. Because “change-request-id” says it “holds the number of a ticket”. That seems very exclusive and specific for a generic element. I think this should just be labeled a “string” and not be so exclusive, and perhaps not mention ticket but just some sort of ID that could be used by external systems. I think the use of “external systems” is OK J

 

Thanks for all of the hard work!

 

- Dave H.

 

Dave Helfinstine

DHelfinstine@ptc.com

 

From: dita-techcomm@lists.oasis-open.org [mailto:dita-techcomm@lists.oasis-open.org] On Behalf Of Jane Credland (jcredlan)
Sent: Monday, October 14, 2013 9:17 PM
To: Bob Thomas; DITA Tech Comm SC
Subject: Re: [dita-techcomm] Review of 13102 stage 3 Release Management

 

Hi Tom,

 

This looks good to me. One note about page 13 of the PDF, there's an incomplete description for change-revisionid

 

Jane

--

Jane Credland

Lead Writer, Data Center Group Technical Documentation

Cisco Technical Communication

Office Phone: 408-424-6468

 

 

From: Bob Thomas <bob.thomas@tagsmiths.com>
Date: Monday, October 14, 2013 10:11 AM
To: "dita-techcomm@lists.oasis-open.org" <dita-techcomm@lists.oasis-open.org>
Subject: [dita-techcomm] Review of 13102 stage 3 Release Management

 

Hi Tom,

 

Nice work. This is nearly ready. However, I do have some technical comments about the implementation.

 

1. File releaseManagement.dtd is unnecessary because domains only get applied within the context of other DTDs such as concept or task. Instead, the proposal needs to describe requirements for integrating the release management domain into each shell DTD where it would be relevant; for instance, concept.dtd or task.dtd
2. releaseManagementDomain.ent and releaseManagementDomain.mod need typical invocation sections in their header comments. These sections show how a public identifier should be defined these files should be defined in a catalog file. See concept.mod and concept.ent for examples.
3. Insert the XML processing instruction above line 1 in the listing for releaseManagementDomain.mod
4. The name attribute ought to be omitted from the change-* elements. The semantic intent for the name attribute in the data element, from which all of these elements inherit, is for the name attribute to be paired with a value attribute. As it is, the default values for the name attributes in releaseManagementDomain.mod simply reflect the element names under which they have been defined, and I can't think of a practical use for that.
5. Change the specialization attribute declarations (the class-attribute definitions) so that they begin with + instead of minus. The + indicates that the element is defined inside of a domain module.

Wrong:

<!ATTLIST change-item              %global-atts;  class CDATA 

          "- topic/data rm-d/change-item ">

 

Correct:

<!ATTLIST change-item              %global-atts;  class CDATA 

          "+ topic/data rm-d/change-item ">

 

Please let me know if I can be of any assistance.

 

Best Regards,

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