Review of Stage 3 Proposals
Two or more individuals who regularly attend the weekly meetings of
the DITA TC must review each Stage 3 proposal before it is submitted
to the TC for discussion and vote.
This purpose of this phase in the process is to ensure that stage 3
proposals have undergone QA and a level of review before being
considered by the TC. It also ensures that the required versions of
the proposal (DITA, HTML, and PDF) are ready for submission to the
TC.
Proposal owner tasks
- Upload the proposal to Kavi in DITA, HTML, and PDF format.
- Notify the TC co-chairs that reviewers are needed
- (After reviewers are assigned) E-mail the assigned reviewers
directly. The e-mail should have a clear subject title (for
example, "Stage 3 review: Proposal X is ready for your
consideration") and provide links to the proposal to be
reviewed.
- Incorporate changes into the proposal and spec topics.
Reviewer tasks
Reviewers need a minimum of one week to conduct their reviews.
Reviewers are requested to complete their reviews within a maximum
of two weeks.
Reviewers should consider the following content areas and points:
Completeness
- Determine whether the proper template has been used
- Determine whether the proposal is complete (stage
3 template)
- Determine whether the proposal is available in the following
forms:
- ZIP of DITA source
- HTML (Must contain all proposal content, including new and
modified spec topics, in a single HTML file)
- PDF (Must contain all proposal content, including new and
modified spec topics, in a single PDF file)
- Determine whether the ZIP of DITA files includes any
extraneous files
(The reason for the single HTML and single PDF file is to make it as
easy as possible for TC members to link on a link in the TC agenda
and open the proposal during TC meetings.)
Proposal content
- Read the proposal carefully and critically.
- Determine whether questions or points that arose during
previous TC discussion of the proposal have been satisfactorily
addressed. Review the minutes at which the proposal was
discussed at the stage 2 level so that you are aware of any
questions or points. (The stage-3 proposal should contain a link
to these minutes.)
Spec topics
- Read new or modified spec topics carefully and critically.
Consider the following points:
- Is the correct terminology used?
- Are the topics free of typos and grammatical errors?
- Are the terms "should," "should not," "must," "must not,"
and "may" used correctly?
- Is the content clear and easy to read?
- If you were reading this content directly out of the
specification, would you consider it a complete description of
the new feature or element?
- If possible, test all new or modified code examples. At a
minimum, test to ensure the code examples are well-formed.
- Assess the quality of the examples. Ideally, they should be
both informative and non-trivial.
--
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)
|