OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita-adoption message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: RE: [dita-adoption] Errors in conref push article (Was "Re: [dita-adoption] Can people offer feedback on the conref push article?")


Hi Paul,
 
Good suggestions. I'll add these to today's agenda.
 
I was thinking perhaps our feature articles should have a "revision history" or "change history" section, where we record each post-release approved set of changes. A simple table that captures the date the change was made (or approved), the person making the changes to the document, and a summary of the changes made.
 
--
Gershon
 


From: Grosso, Paul [mailto:pgrosso@ptc.com]
Sent: Monday, November 23, 2009 4:57 PM
To: DITA Adoption
Subject: RE: [dita-adoption] Errors in conref push article (Was "Re: [dita-adoption] Can people offer feedback on the conref push article?")

All of Gershon's comments are editorial to the point of being barely more than "typos".  But one person's typo is another person's substantive change, and rather than argue what's editorial and what's not, it would be nice to have a procedure that allows us to approve small changes to our articles.

 

Drawing on what we do in the W3C's XML Core WG for errata (but making it a bit more light weight for our purposes), I think we should develop a policy for editing published articles that goes something like this:

 

* the list of suggested editorial changes gets posted to the mailing list

* at the next TC meeting, we have a short agenda item that references the mail and gives everyone notice that these changes are planned to be made after a two-week countdown period

* at the following TC meeting (two weeks later), we have a short agenda item that provides a final point where someone can object, and then we record in the minutes that these changes have been approved, and we give the article editor an action to do so

* I think it's important that the date of the article reflect the latest edits. Perhaps we can leave the original publication date and add something like (Date of last minor revisions: 28 November 2009).

 

I suggest we add two items to the agenda for today's meeting:

 

1.  approval of a procedure such as I outline above

2.  the start of a two week countdown for approving Gershon's suggested errata

 

paul

 

From: Kristen James Eberlein [mailto:keberlein@pobox.com]
Sent: Sunday, 2009 November 22 12:55
To: Gershon Joseph (gerjosep)
Cc: DITA Adoption
Subject: [dita-adoption] Errors in conref push article (Was "Re: [dita-adoption] Can people offer feedback on the conref push article?")

 

Hey, Gershon. Thanks for catching the mistakes.

I've been assuming -- but I think we ought to make it upfront -- that it is OK to refresh the feature articles periodically as we notice minor errors.

But that then does raise the question of where we do draw a line. At what point does an article need to be re-approved by the TC? And should we use some sort of version marking? I guess I'll cc the list about this ...

Kris



Gershon Joseph (gerjosep) wrote:

Hi Kris,
 
This is a great article. Some minor editorial nits:
 
1. In the Overview section, the second paragraph contains the text
"Until DITA 1.2., the conref mechanism...". The period of the 1.2 should
be removed.
 
2. Figure 4's caption is on the next page. It should keep with the image
on the previous page (or the figure should keep with its caption on the
next page).
 
3. Figure 5 contains a comment "Resource file that contain content to be
pushed". I think this should be "Resource file that *contains* content
to the pushed".
 
4. In Figure 6, maybe we should highlight the "conaction="pushbefore"
text to be consistent with the other figures? OTOH that's not the only
thing of interest in this figure, since the while <step> that precedes
the "mark" step is here. So I'm in 2 minds on this one, but thought I'd
bring it up anyway.
 
5. The note following Figure 8 contains the text "and the @conaction
attribute to set to "pushreplace".". I think it should read "and the
@conaction attribute *is* set to "pushreplace"."
 
6. In the Rules and restrictions section, I'm not sure the word
"prefaced" is correct here. Perhaps "preceded" would be better?
 
7. In the third-last paragraph of the article, we have the following
sentence:
According to the DITA 1.2 specification: "Applications may, but need
not, warn users if more than element attempts to replace a single
target."
There is a missing word. It should read:
According to the DITA 1.2 specification: "Applications may, but need
not, warn users if more than *one* element attempts to replace a single
target."
Please could you ensure this is also fixed in the DITA 1.2 spec -- or
let me know and I'll do the necessary check for us.
 
Again, this is a truly valuable article I want to share here at Cisco.
But I know my stakeholders -- they will moan and grown if the article
has any mistakes ;-)
 
Thanks for putting this together. Excellent work as always.
 
Cheers,-
Gershon
 
-----Original Message-----
From: Kristen James Eberlein [mailto:keberlein@pobox.com] 
Sent: Thursday, September 17, 2009 7:07 PM
To: dita-adoption@lists.oasis-open.org
Subject: [dita-adoption] Can people offer feedback on the conref push
article?
 
 
  

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



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]