OASIS Darwin Information Typing Architecture (DITA) TC

 View Only
  • 1.  Groups - Proposal 13102, Stage 2 Release Management (PDF) uploaded

    Posted 08-23-2013 20:34
    Submitter's message PDF version of release management stage 2 proposal -- Tom Cihak Document Name : Proposal 13102, Stage 2 Release Management (PDF) Description Proposal 13102, Stage 2 Release Management PDF Download Latest Revision Public Download Link Submitter : Tom Cihak Group : OASIS Darwin Information Typing Architecture (DITA) TC Folder : Drafts Date submitted : 2013-08-23 13:33:50


  • 2.  Re: [dita] Groups - Proposal 13102, Stage 2 Release Management (PDF) uploaded

    Posted 08-24-2013 04:11
    Hi Tom, Thanks for the new submission.  I do have one comment.   I notice that the <change-summary> element is specialized from <data>   As someone who's written lots of release notes in my time, I can say that some release notes are significantly more complex than the ones in your examples, and more complex than is allowed within any of data's child elements, with the exception of <foreign>/<desc> (which allows 'p' and 'note').  Is that what you had in mind for anyone needing a long, complex release note?  If so, I'd suggest creating an element - maybe 'change-long-summary'? -  specializing off foreign (and perhaps only allowing <desc>), so there's an element within change-summary that will guide an author in creating a long release note description. This would mean altering the <!ENTITY % change-summary.content "(%data.cnt;)*"> to < !ENTITY % change-summary.content "(%data.cnt;)* %change-long-summary.cnt;"> And adding a change-long-summary element such as: <!-- Long Name: Change Long Summary container for a long or complex release note description that requires the inclusion of one or more block elements --> <!ENTITY % change-long-summary.content "(%desc.cnt;)*" > <!ENTITY % change-long-summary.attributes '%changehistory.data.atts; name CDATA "change-long-summary" ' > <!ELEMENT change-long-summary %change-long-summary.content; > <!ATTLIST change-long-summary %change-long-summary.attributes; > with the following class attribute: <!ATTLIST change-long summary %global-atts;     class CDATA "- topic/foreign rm-d/change-long-summary "> If you don't create a specific long-summary specialization, then the documentation for change-summary will need to note that if someone has to create a complex summary, they can use foreign/desc to do it.  Most authors don't use foreign as a general rule, and might not be familiar with its content model, and its name doesn't sound like something you'd put a summary in. Nice job on the general structure. Regards, Nancy On Fri, Aug 23, 2013 at 1:33 PM, Tom Cihak < r65612@freescale.com > wrote: Submitter's message PDF version of release management stage 2 proposal -- Tom Cihak Document Name : Proposal 13102, Stage 2 Release Management (PDF) Description Proposal 13102, Stage 2 Release Management PDF Download Latest Revision Public Download Link Submitter : Tom Cihak Group : OASIS Darwin Information Typing Architecture (DITA) TC Folder : Drafts Date submitted : 2013-08-23 13:33:50 -- _____________ Nancy Harrison Infobridge Solutions  nharrison@infobridge-solutions.com


  • 3.  Re: [dita] Groups - Proposal 13102, Stage 2 Release Management (PDF) uploaded

    Posted 08-24-2013 15:50
    I think it would be a misuse of <foreign> to use it merely to get around the lack of block elements within <data>. If we think block elements should be allowed in <data> we should expand the scope of my proposal 13044, basic-ph in <data> to include at least <p>, <ul>, <ol>, <sl>, <div>, and <note>, if not also <fig> and <table>, and <image>. There is an argument to be made that we should not restrict, at the base level, the content model of <data> because who are we to say what it is reasonable for metadata and what is not? In this case, as Nancy points out correctly, I think, a change comment could be quite involved, but it is also clearly semantically metadata about the thing changed, not content (in the rhetorical sense) of the thing changed. On the other hand, if the primary use case is to generate either typical change lists (e.g., "list of effective pages" and whatnot) or things like change tracking spreadsheets, allowing block content would complicate both of those, where otherwise they would be relatively straightforward to implement. Because the change descriptions are metadata applied to the topic or map, they must go in <prolog> or <topicmeta>, which pretty much limits your specialization options to <metadata> and <data>. I suggested using <metadata> as the base for <change-historylist> so that it could only go in <prolog> or <topicmeta>. The alternative would be to define new base element types so that there would be no pre-existing content model constraints. Cheers, Eliot On 8/23/13 11:10 PM, "Nancy Harrison" <nharrison@infobridge-solutions.com> wrote: > Hi Tom, > > Thanks for the new submission.  I do have one comment.   I notice that the > <change-summary> element is specialized from <data>   As someone who's written > lots of release notes in my time, I can say that some release notes are > significantly more complex than the ones in your examples, and more complex > than is allowed within any of data's child elements, with the exception of > <foreign>/<desc> (which allows 'p' and 'note').  Is that what you had in mind > for anyone needing a long, complex release note?  > > If so, I'd suggest creating an element - maybe 'change-long-summary'? -  > specializing off foreign (and perhaps only allowing <desc>), so there's an > element within change-summary that will guide an author in creating a long > release note description. > > This would mean altering the > <!ENTITY % change-summary.content "(%data.cnt;)*"> > to > <!ENTITY % change-summary.content "(%data.cnt;)* %change-long-summary.cnt;"> > > And adding a change-long-summary element such as: > > <!-- Long Name: Change Long Summary > container for a long or complex release note description that requires > the inclusion of one or more block elements > --> > <!ENTITY % change-long-summary.content > "(%desc.cnt;)*" >> > <!ENTITY % change-long-summary.attributes > '%changehistory.data.atts; > name > CDATA > "change-long-summary" > ' >> > <!ELEMENT change-long-summary %change-long-summary.content; > > <!ATTLIST change-long-summary %change-long-summary.attributes; > > > with the following class attribute: > > <!ATTLIST change-long summary %global-atts; >     class CDATA "- topic/foreign rm-d/change-long-summary "> > > > If you don't create a specific long-summary specialization, then the > documentation for change-summary will need to note that if someone has to > create a complex summary, they can use foreign/desc to do it.  Most authors > don't use foreign as a general rule, and might not be familiar with its > content model, and its name doesn't sound like something you'd put a summary > in. > > Nice job on the general structure. > > Regards, > Nancy > > > > On Fri, Aug 23, 2013 at 1:33 PM, Tom Cihak <r65612@freescale.com> wrote: >> Submitter's message >> PDF version of release management stage 2 proposal >> -- Tom Cihak >> Document Name: Proposal 13102, Stage 2 Release Management (PDF) >> < https://www.oasis-open.org/apps/org/workgroup/dita/document.php?document_id= >> 5 >> 0423> >> >> >> Description >> Proposal 13102, Stage 2 Release Management PDF >> Download Latest Revision >> < https://www.oasis-open.org/apps/org/workgroup/dita/download.php/50423/latest >> / >> proposal_13102_release_management_Stage2.pdf> >> Public Download Link >> < https://www.oasis-open.org/committees/document.php?document_id=50423&wg_abbr >> e >> v=dita> >> >> >> Submitter: Tom Cihak >> Group: OASIS Darwin Information Typing Architecture (DITA) TC >> Folder: Drafts >> Date submitted: 2013-08-23 13:33:50 >> >> > > -- Eliot Kimber Senior Solutions Architect, RSI Content Solutions "Bringing Strategy, Content, and Technology Together" Main: 512.554.9368 www.rsicms.com www.rsuitecms.com Book: DITA For Practitioners, from XML Press, http://xmlpress.net/publications/dita/practitioners-1/


  • 4.  Re: [dita] Groups - Proposal 13102, Stage 2 Release Management (PDF) uploaded

    Posted 08-24-2013 19:31
    If we were to expand the <data> element proposal to allow more text, we would not have to change Tom's proposal at this time. I think that would be easier and not overly affect our deadline for Stage 2. JoAnn Sent from my iPad JoAnn Hackos Comtech Services Inc 710 Kipling Street Suite 400e Lakewood CO 80215 On Aug 24, 2013, at 9:49 AM, "Eliot Kimber" <ekimber@rsicms.com> wrote: > I think it would be a misuse of <foreign> to use it merely to get around the > lack of block elements within <data>. > > If we think block elements should be allowed in <data> we should expand the > scope of my proposal 13044, basic-ph in <data> to include at least <p>, > <ul>, <ol>, <sl>, <div>, and <note>, if not also <fig> and <table>, and > <image>. There is an argument to be made that we should not restrict, at the > base level, the content model of <data> because who are we to say what it is > reasonable for metadata and what is not? In this case, as Nancy points out > correctly, I think, a change comment could be quite involved, but it is also > clearly semantically metadata about the thing changed, not content (in the > rhetorical sense) of the thing changed. > > On the other hand, if the primary use case is to generate either typical > change lists (e.g., "list of effective pages" and whatnot) or things like > change tracking spreadsheets, allowing block content would complicate both > of those, where otherwise they would be relatively straightforward to > implement. > > Because the change descriptions are metadata applied to the topic or map, > they must go in <prolog> or <topicmeta>, which pretty much limits your > specialization options to <metadata> and <data>. I suggested using > <metadata> as the base for <change-historylist> so that it could only go in > <prolog> or <topicmeta>. > > The alternative would be to define new base element types so that there > would be no pre-existing content model constraints. > > Cheers, > > Eliot > > On 8/23/13 11:10 PM, "Nancy Harrison" <nharrison@infobridge-solutions.com> > wrote: > >> Hi Tom, >> >> Thanks for the new submission. I do have one comment. I notice that the >> <change-summary> element is specialized from <data> As someone who's written >> lots of release notes in my time, I can say that some release notes are >> significantly more complex than the ones in your examples, and more complex >> than is allowed within any of data's child elements, with the exception of >> <foreign>/<desc> (which allows 'p' and 'note'). Is that what you had in mind >> for anyone needing a long, complex release note? >> >> If so, I'd suggest creating an element - maybe 'change-long-summary'? - >> specializing off foreign (and perhaps only allowing <desc>), so there's an >> element within change-summary that will guide an author in creating a long >> release note description. >> >> This would mean altering the >> <!ENTITY % change-summary.content "(%data.cnt;)*"> >> to >> <!ENTITY % change-summary.content "(%data.cnt;)* %change-long-summary.cnt;"> >> >> And adding a change-long-summary element such as: >> >> <!-- Long Name: Change Long Summary >> container for a long or complex release note description that requires >> the inclusion of one or more block elements >> --> >> <!ENTITY % change-long-summary.content >> "(%desc.cnt;)*" >> <!ENTITY % change-long-summary.attributes >> '%changehistory.data.atts; >> name >> CDATA >> "change-long-summary" >> ' >> <!ELEMENT change-long-summary %change-long-summary.content; > >> <!ATTLIST change-long-summary %change-long-summary.attributes; > >> >> with the following class attribute: >> >> <!ATTLIST change-long summary %global-atts; >> class CDATA "- topic/foreign rm-d/change-long-summary "> >> >> >> If you don't create a specific long-summary specialization, then the >> documentation for change-summary will need to note that if someone has to >> create a complex summary, they can use foreign/desc to do it. Most authors >> don't use foreign as a general rule, and might not be familiar with its >> content model, and its name doesn't sound like something you'd put a summary >> in. >> >> Nice job on the general structure. >> >> Regards, >> Nancy >> >> >> >> On Fri, Aug 23, 2013 at 1:33 PM, Tom Cihak <r65612@freescale.com> wrote: >>> Submitter's message >>> PDF version of release management stage 2 proposal >>> -- Tom Cihak >>> Document Name: Proposal 13102, Stage 2 Release Management (PDF) > < https://www.oasis-open.org/apps/org/workgroup/dita/document.php?document_id= >> > 5 >>> 0423> >>> >>> >>> Description >>> Proposal 13102, Stage 2 Release Management PDF >>> Download Latest Revision > < https://www.oasis-open.org/apps/org/workgroup/dita/download.php/50423/latest >> > / >>> proposal_13102_release_management_Stage2.pdf> >>> Public Download Link > < https://www.oasis-open.org/committees/document.php?document_id=50423&wg_abbr >> > e >>> v=dita> >>> >>> >>> Submitter: Tom Cihak >>> Group: OASIS Darwin Information Typing Architecture (DITA) TC >>> Folder: Drafts >>> Date submitted: 2013-08-23 13:33:50 > > -- > Eliot Kimber > Senior Solutions Architect, RSI Content Solutions > "Bringing Strategy, Content, and Technology Together" > Main: 512.554.9368 > www.rsicms.com > www.rsuitecms.com > Book: DITA For Practitioners, from XML Press, > http://xmlpress.net/publications/dita/practitioners-1/ > > > --------------------------------------------------------------------- > To unsubscribe from this mail list, you must leave the OASIS TC that > generates this mail. Follow this link to all your TCs in OASIS at: > https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php >


  • 5.  RE: [dita] Groups - Proposal 13102, Stage 2 Release Management (PDF) uploaded

    Posted 08-30-2013 20:53
    Tom,   I reviewed the proposal in light of my clients’ requirements and really liked the way you propose to handle the multiple-product/concurrent release challenge. Overall, I think that the strategy of using the topic <prolog> and the structure of the domain are sound.   However, the one item I didn’t see addressed is the requirement to visually indicate the exact location of the change in the content of the topic. It seems to me that the <change-item> needs to reference the modified element and it comes down to the selection of the appropriate DITA referencing mechanism. Has the subcommittee considered the options for providing this support?   The challenge for many teams is the they need to visually indicate changes between releases of a deliverable, but the track changes features in most tools don’t work for the following reasons: ·          author may want to identify a subset of content changes based on specific criteria, such as importance or relevance ·          changes may not correspond cleanly to the workflow versions/revisions of the topic file and the releases of the deliverable   Thanks and have a great weekend, Amber   Amber Swope dita specialist <dita strategies> 503.922.3038 amber@ditastrategies.com       From: dita@lists.oasis-open.org [mailto:dita@lists.oasis-open.org] On Behalf Of Tom Cihak Sent: Friday, August 23, 2013 1:34 PM To: dita@lists.oasis-open.org Subject: [dita] Groups - Proposal 13102, Stage 2 Release Management (PDF) uploaded   Submitter's message PDF version of release management stage 2 proposal -- Tom Cihak Document Name : Proposal 13102, Stage 2 Release Management (PDF) Description Proposal 13102, Stage 2 Release Management PDF Download Latest Revision Public Download Link Submitter : Tom Cihak Group : OASIS Darwin Information Typing Architecture (DITA) TC Folder : Drafts Date submitted : 2013-08-23 13:33:50  


  • 6.  Re: [dita] Groups - Proposal 13102, Stage 2 Release Management (PDF) uploaded

    Posted 08-31-2013 14:32
    Amber, thanks for taking the time to review the proposal; I appreciate it. Best, Kris Kristen James Eberlein Principal consultant, Eberlein Consulting Co-chair, OASIS DITA Technical Committee Charter member, OASIS DITA Adoption Committee www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype) On 8/30/2013 4:52 PM, Amber Swope wrote: Tom,   I reviewed the proposal in light of my clients’ requirements and really liked the way you propose to handle the multiple-product/concurrent release challenge. Overall, I think that the strategy of using the topic <prolog> and the structure of the domain are sound.   However, the one item I didn’t see addressed is the requirement to visually indicate the exact location of the change in the content of the topic. It seems to me that the <change-item> needs to reference the modified element and it comes down to the selection of the appropriate DITA referencing mechanism. Has the subcommittee considered the options for providing this support?   The challenge for many teams is the they need to visually indicate changes between releases of a deliverable, but the track changes features in most tools don’t work for the following reasons: ·          author may want to identify a subset of content changes based on specific criteria, such as importance or relevance ·          changes may not correspond cleanly to the workflow versions/revisions of the topic file and the releases of the deliverable   Thanks and have a great weekend, Amber   Amber Swope dita specialist <dita strategies> 503.922.3038 amber@ditastrategies.com       From: dita@lists.oasis-open.org [ mailto:dita@lists.oasis-open.org ] On Behalf Of Tom Cihak Sent: Friday, August 23, 2013 1:34 PM To: dita@lists.oasis-open.org Subject: [dita] Groups - Proposal 13102, Stage 2 Release Management (PDF) uploaded   Submitter's message PDF version of release management stage 2 proposal -- Tom Cihak Document Name : Proposal 13102, Stage 2 Release Management (PDF) Description Proposal 13102, Stage 2 Release Management PDF Download Latest Revision Public Download Link Submitter : Tom Cihak Group : OASIS Darwin Information Typing Architecture (DITA) TC Folder : Drafts Date submitted : 2013-08-23 13:33:50