OASIS has very clear policies for handling public
review comments. (These rules apply whether or not the
review of is a standard work track product (spec) or a
non-standards track work product (committee note).
You can view the rules at https://www.oasis-open.org/policies-guidelines/tc-process-2017-05-26#publicReview
, but here is a brief summary:
- All review comments (e-mails to TC list or e-mails to
dita-comment) must be formally acknowledged.
- All review comments must be formally tracked.
- At the close of the review, the TC must post to its
e-mail list how it handled each review comment.
As spec editors, Robert and I handled the tracking for the
DITA 1.2 and 1.3 releases in several ways:
- DITA 1.2: We used a Wiki page to track the
comments and generated a PDF of it for the formal posting.
- DITA 1.3: We used a Wiki page to track the
comments and generated a PDF of it for the formal posting.
We tracked the changes to the source files in a
spreadsheet:
- DITA 1.3 Errata 01: We used a DITA topic to track
the comments; the changes to the source were tracked
explicitly in the "Errata 01 document":
When you do a public review of a document, you need to
track the changes that you make to the source -- especially
to determine whether or not they are "material." If changes
are "material," then the document needs to go out for
additional public reviews until no more material changes are
made.
My personal opinion: Using a DITA topic to track comments,
their resolution, etc. was the best approach. The only
drawback was that we had to generate output in order for TC
members to see work in progress. Robert, your thoughts?
Obviously, there is work to be assigned and processes to
be clarified:
- Who acknowledges each comment on the dita-comment list?
- Who maintains the comment resolution log?
- Whether to use a Wiki page or DITA topic for the comment
resolution log?
- Which comments are brought to the TC for discussion?
Which comments will editors immediately fix and then
notify the TC?
- Does the subcommittee want to play an intervening role?
For example, does subcommittee make tentative comment
resolution and then refer to the TC? (Note: This will take
more time.)
Lots to talk over and digest. I apologize in advance for
the lengthy e-mail, but I don't see how I could have made it
shorter.
--
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 682-2290; kriseberlein (skype)