Review of 13102 stage 3 Release Management

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:
 [mailto:]  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

From:
 [mailto:]  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 < 
>
Date:  Monday, October 14, 2013 10:11 AM
To:  "  " < 
>
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.

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
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.
Insert the XML processing instruction above line 1 in the listing for releaseManagementDomain.mod
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.
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 (  ) or Skype
Time zone: Mountain (GMT-7)