7. Guidance for Reviews
This chapter provides guidance on reviews – the process by which The Open Group measures consensus around a document. Different kinds of review with varying levels of formality may be held during the development of a draft document. The Open Group Document Review system can be useful for all of these reviews, and provides a number of different review modes: “informal, formal, and company review”.
All reviews must be conducted in accordance with the guiding principles for Forums and Work Groups. There are specific rules used to finalize documents of different types, and at specific checkpoints. The specific processes for these reviews are described in the preceding chapters, and processes that are common to all of them are described in the following sections.
The review process includes the examination of a document, the submission of Change Requests by reviewers against the document, the resolution of those Change Requests (through a recommendation and ballot), and if applicable updates to the document arising from the review. A review process is often repeated through multiple drafts of a document. Aspects of this process can be applied to documents on all development tracks within The Open Group. A review process is under the lead of The Open Group Manager responsible for the work program.
7.1. Choosing the Ballot Resolution Type
The review announcement should state the type of ballot resolution, whether it is to be against the original Change Requests or against proposed resolutions formulated by the sponsor. The latter is recommended, since that can arrive at more consistent changes to be applied to the review document.
7.2. Creating Change Requests
All requests to modify a review document must be the subject of a formal Change Request and should be submitted either by email to the notified address for email comments, or via The Open Group Document Review system.
There is a standard format for Change Requests (see Section 3.3.2.1 of the Standards Process). The key fields are described below.
When submitting a Change Request, the submitter can indicate the severity and nature of the Change Request, as follows:
7.2.1. Severity
-
Critical – a show stopper; we will vote against publication of the document unless this is changed the way we want it
-
Major – a serious problem that must be fixed; we are proposing a solution but are ready to compromise
-
Minor – a nuisance; we won’t fuss if it is not fixed our way
7.2.2. Nature
-
Technical – when changing anything in the technical content
-
Editorial – when changing only text without changing content; can be applied by the editors without discussion
7.2.3. Specific Changes to the Text
A Change Request must include unambiguous identification of the precise text or illustration, where the change is needed, and quoted text if required.
It should include explicit instructions using keywords to make the change unambiguous; i.e., add, create, change, delete, move, merge, rename, replace, restore, update. For example, change from: existing text to: new proposal, or insert words before existing text, or delete the second sentence.
There may be cases where a reviewer feels they are unable to provide text; for example, where a clarification is requested. In such cases there are two options:
-
Write down one of the possible alternatives; this at least serves to illustrate the concern
-
Contact someone else, in advance, who may be able to suggest some wording, before submitting a Change Request
7.2.4. Rationale
A Change Request must include the reason that the change is needed; the reason that suggested change is preferred over other possibilities, etc. This is the opportunity to persuade other reviewers to support the Change Request.
7.3. Submitting a High-Impact Change Request
If a Change Request impacts multiple areas of the review document, then it is recommended to raise the general issue in a single place, and in that Change Request to identify all the other changes required in the document. This will enable reviewers to:
-
Understand the problem and take a position on whether they agree or not
-
Understand the full impact of the issue and the proposed change, and decide whether that is correct
It will also allow the editors to make the complete change if the Change Request is accepted.
7.4. Replacing a Large Passage of Text in a Change Request
If a Change Request is proposing replacement of a large passage of text including images, then the Change Request should clearly identify the text to be replaced using chapter and section numbering (if applicable) and then reference an external document that has been uploaded to the repository for the Forum/Work Group. The uploaded document will need to be in PDF or HTML format, together with a revisable format.
7.5. If you Disagree with a Change Request
During a review, if you disagree with a Change Request that has been submitted there are a number of actions that could be taken:
-
Submit a competing Change Request with an opposing view
The two Change Requests would then be considered as a competing pair at the meeting to create proposed resolutions.
-
Argue against the original Change Request at the proposed resolution meeting
-
Vote against the item in the ballot if the proposed resolution on the Change Request is not acceptable
-
Submit a Change Request in the following review cycle
7.6. Creating Proposed Resolutions
At the end of a review the sponsor will prepare a proposed resolution for each submitted Change Request. The procedure for doing this should be as all-inclusive as possible. It may take the form of a face-to-face meeting (particularly applicable if there is a large number of Change Requests) or a series of one or more teleconferences.
Prior to the meeting, a report of the “raw” Change Requests received in the review will be circulated at least seven (7) days in advance. The Open Group Technical Editor may make a pass of the Change Requests and add initial recommendations from the editors.
Proxy positions are not permitted in a meeting to formulate proposed resolutions; however, written positions on Change Requests submitted at least 48 hours in advance of the meeting would be accepted. These must be sent to The Open Group Manager and must use one of the four standard dispositions below.
When formulating a proposed resolution, the sponsor uses four standard dispositions:
-
Accept – the proposed resolution is to accept the Change Request as written (with no modification)
-
Accept as Marked – the proposed resolution accepts that there is a problem, but proposes an alternate way to resolve the problem
The “as marked” text provided with the proposed resolution describes the action proposed to resolve the problem.
-
Duplicate – the proposed resolution to another Change Request resolves the issue raised by this Change Request
The proposed resolution for this Change Request is to mark it as a duplicate and reference the other Change Request. No action is required on this item if the other proposed resolution to the referenced Change Request is accepted in the ballot.
-
Reject – the proposed resolution to the Change Request is to reject it
In this case the proposed resolution will include rationale as to why the Change Request is being rejected.
7.7. Balloting Proposed Resolutions
The process for balloting proposed resolutions is as per Section 3.3.2.3 of the Standards Process.
7.8. Issue Resolution Meetings
An issue resolution meeting is held to resolve proposed resolutions that did not achieve resolution in the ballot. This should be held as a video or teleconference. Proxy voting is not allowed; however, those unable to attend the meeting can submit email votes so long as they are submitted at least 24 hours in advance. This is under the lead of The Open Group Manager.
Issue resolution should follow Section 3.3.2.3 of the Standards Process.
7.9. Informal Reviews
As noted at the start of this chapter, different kinds of review with varying levels of formality may be held during the development of a document. This section contains advice for informal reviews during the Draft Development Process.
The following considerations should be taken into account:
-
An early draft need not have an editorial review or editorial pass by The Open Group Technical Editor
-
The review period could be as little as one (1) week after the one-week review announcement
-
The next steps depend on the number of planned drafts
-
If the document is a candidate for Company Review (for a Standard) or publication (for a Guide or White Paper) then the applicable formal review should follow
-
If the document is for internal use only at this stage, then the review should terminate