dita-techcomm — archive

Review of 13102 stage 3 Release Management

From: David Helfinstine <[email protected]>
To: [email protected]
Date: Mon, 28 Oct 2013 17:56:00 -0000

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 [email protected] From: [email protected] [mailto:[email protected]] 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 < [email protected] > Date: Monday, October 14, 2013 10:11 AM To: " [email protected] " < [email protected] > 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 ( [email protected] ) or Skype Time zone: Mountain (GMT-7)