Peer reviews

When the draft document has reached an appropriate stage, the technical author shall arrange an initial peer review within his or her team/group.

Initial peer review checks that the criteria by which the document is considered a success have been met and ensures that any issues that were identified can be investigated, discussed and resolved before the document progresses to review by the TSC.

Peer reviewers can raise discussions and comments on the live document, however it is still recommended that a version of type ‘Draft for peer review’ is created (ensuring that ‘Available to reviewers’ is not checked).

Consultation

Preparing a version for Consultation

Consultation is performed on a version on a document in CARS. This ensures that all consultees make comments against the same version of the document. Please see the question “How do I create a version of a document?” to learn how to create a version of your document.

Before the Consultation

Preliminary checks

• Read the requirements in the MDD for Consultation (MDD part 1).
• Give your peer reviewers enough time to review your document before you submit it for Consultation.
• Resolve all of the MDD validation errors in your document. You will not be able to publish the document with errors.
• Complete references using CARS functionality. Using the CARS referencing feature will allow the publishing team to determine if a document can be published.
• For brand new documents where it has not previously been published in CARS, complete the change log in CARS for your document. For updated documents, generate a Clause Change Summary in CARS.
• Complete the background commentary in CARS for all newly drafted or updated clauses. This is important as it will appear as a column in the clause change summary and will help reviewers to know why you made the change or added the new text.
• Consult with your Content Specialist and give sufficient notice to allow them to complete a review for MDD compliance before submission to the TSC for consultation. NOTE CARS does not warn you of all MDD errors and the Content Specialist review will assist with this.

Governance deliverables and versioning

• Before submitting the draft CARS document (category A) or the draft CARS clauses (categories B, C) to the TSC for consultation, the technical author shall complete a pre-consultation impact assessment (cat A, B, C only) identifying the anticipated impacts of the work (including when there is no impact or a negative impact) and a commercial impact assessment. See MDD part 1 and the standards governance technical author training video for further guidance if needed.
• All consultees shall be added as reviewers to your document. A list of current TSC consultees can be found here. See ‘Adding users to a CARS document’ for more information and how to add users who do not have a CARS account.
• Create a version. Reviewers can only see versions of a document. Remember to make the version available to read, and available to comment. You may wish to uncheck the ‘Available to reviewers’ box for other versions, so reviewers are not confused.
• Within the version, open the clause change summary (see the … menu on the document information page) and copy the link at the top of the page to be shared with the reviewers in the notification email.
• Please contact the TSG team for support (Standards_Enquiries@nationalhighways.co.uk) if you need review comments from:
  an industry board that needs to consolidate their response across multiple parties; an organisation that can ONLY use Internet Explorer as its web browser.
• Please create a PDF copy of your finalised impact assessment report to attach to the email to consultees.
• There is an excel template for your consultees to add any comments related to the impact assessment report (example here). Please save a copy of this template to your own governance folders (where governance deliverables are stored) in DMRB or MCHW as appropriate as a link will be shared in the notification email.
• Update your change issue in Jira to record that you have sent your document out for consultation. Further guidance on how to record governance in Jira can be found here.

Notifying consultees

This is some suggested text to send by email to your consultees. Please copy and paste the text into an email and edit the text in italics as appropriate before sending out.

Notice of the forthcoming consultation

Sending the document out to consultation

Encourage consultees to read each others comments, and discuss any differing views.

During the Consultation

You can see consultees’ comments as they are added to CARS, and you may respond immediately to them if you need more clarity.

After the Consultation

• Ensure that all comments have been recorded in CARS.
• Resolve every discussion. You can either accept or reject each one.
• Make updates to the document.
• Create a new version of the document.
• Send a link to the new version to reviewers.

Conclusion of the consultation

Review Status

On the My Discussions dashboard

The ‘My Discussions’ dashboard lists all documents for which you are assigned a role, and provides an overview of all the discussions and comments that you have raised against those documents.  The dashboard also allows reviewers to set the status of their review for each document.  The review status follows the flow outlined below:

The review status is visible to Lead Authors in the My Documents dashboard and hence this functionality can be used to easily share your review progress. To learn more, please watch this video.

On the Version Information page

To make it as easy as possible for reviewers to record the status of the their review, the functionality from the ‘My Discussions’ dashboard has also been incorporated into the Version Information page.

On the My Documents dashboard

The ‘My Documents’ dashboard provides an overview of all the discussions on documents where you are the Lead Author.  The dashboard also displays the review status for each reviewer on each document.  This can be used to help answer questions like “Are all the reviews completed on the latest version of my document?”, “Has a review been completed for every NAA?”, and “Has a reviewer completed their review before I respond to their comments?”.  To learn more, please watch this video.

Discussions

Adding a new discussion

To add a discussion:

• Select a clause within the current section. To select a clause, simply click anywhere within the clause or select some of the clause’s content. You can easily identify the selected clause by the blue bar visible within the left margin.

• On the right hand sidebar, click the Discussions icon (resembling two speech bubbles). The Discussions side pane will be displayed.

• At the top of the Discussions side pane, the ‘Manage discussions for’ selection field will confirm the index reference for the currently selected clause. If the selected clause has sub-content, i.e. a table, figure and or equation, then the index reference may reflect that content if it is selected.
  • The ‘Manage discussions for’ can be used to specify the clause’s content that you wish to start a discussion above.
  • The option is also provided to be able to select the Section. This option can be used when you want to comment on the whole section, rather than just one clause or a clauses sub-content.
• With the relevant item selected using the ‘Manage discussions for’ selector, simply click ‘Start new discussion’ to add a new discussion.

• Enter the text of your discussion into the ‘Discussion’ field provided.
• Next, categorise your discussion as to whether it is General, Editorial or Technical in nature.
• You then confirm the capacity in which you are raising a discussion using the ‘In the capacity of’ field provided.
• At this point you could ‘Submit’ your discussion. However, you may also want to propose a suggestion for alternative text as part of your discussion.

• To propose alternative text:
  • with your discussion still open prior to being submitted
  • select the text within the clause for which you wish to provide an alternative suggestion
  • having select some text, the ‘Include suggestion’ checkbox will be enabled
  • Checking this checkbox will provide you with the option to enter some suggested text
  • Enter your alternative text suggestion
• Clicking ‘Submit’ will save your discussion.

Please note that if you select another clause or navigate away from the current section or page, any text entered will be lost. Please also note that currently CARS does not support editing of discussions once they have been saved.

Identifying clauses which have discussions

Once a discussion has been added to a clause a ‘unresolved discussion icon’ is shown to the right of the clause (or sub-content if the discussion was raised against a table, figure or equation).

The number of unresolved discussions is shown as a number within the discussion icon. Any alternative text suggestions are also highlighted as shown in the figure below.

Reviewing discussions

Clicking on the discussion icon to the right of the clause will open the Discussion side pane for the associated clause.

The discussion summary provides the following information:

• Confirmation of who raised the discussion
• Whether the discussion was raised against the core clause content, or its sub-content
• The date and time that the discussion was raised
• The capacity in which the discussion’s author was working on behalf of
• Confirmation of the category for the discussion (general, editorial, or technical)
• The text of the discussion
• If relevant, the current text and suggested alternative.

Commenting on a discussion

Having reviewed an existing discussion (see above), you can easily add your own comments to it using the ‘Comment’ option provided.

Having clicked ‘Comment’, you will be prompted to enter your comment and then click ‘Submit’ to save your comment. You can click ‘Cancel’ if you decide not to add a comment.

Submitted comments are summarised underneath the original comment.

Please note that once a comment has been made you cannot edit or delete it.

Resolving discussions

Document authors can record discussions as resolved once all comments have been addressed.

Clicking the ‘Resolve’ option beneath the discussion summary will prompt for a ‘Resolution’ comment. If a suggestion for alternative text has been provided then options are provided to ‘Resolve and accept’, ‘Resolve and reject’ or ‘Cancel’.

Clicking ‘Resolve and accept’ will automatically update the clause text based on the suggestion and mark the discussion as resolved. Clicking ‘Resolve and reject’ will not affect any change on the clause text and the discussion will be marked as resolved. If there are no remaining unresolved discussions against the associated clause then the ‘unresolved discussion icon’ will be removed from the right hand margin; otherwise the counter will be reduced by one.

If no suggestion for alternative text has been provided, then options for ‘Resolve’ and ‘Cancel’ are provided.

Resolved discussions against a clause can be viewed at any time by clicking on the ‘Resolved (#)’ tab beneath the ‘Manage discussions for’ selector. The number of resolved discussions is shown as part of the tab title.

Deleting discussions

Please note, discussions can only be deleted if they have not been commented on or resolved, and only by the author of the discussion.

To delete a comment, locate it within the Discussions side pane (quickly accessed by clicking on the unresolved discussion icon to the right of the respective clause), then click on the ‘Delete’ option provided at the bottom of the discussion summary.

You will be prompted for confirmation. Either click ‘Delete’ to delete the discussion, or ‘Cancel’ to abort the delete action.

Please note, deletion of discussion cannot be undone.

Discussion permissions

Discussions and comments on discussions can be created on the live document by Lead Authors, Authors and Peer Reviewers.

Reviewers can only create discussions and comments on discussions if the version shared with them has been configured to ‘Allow discussions and comments’. A further version configuration option can also be used to limit Reviewer access to only see and comment on their own discussions. The screenshot below shows these options as part of version creation.

Exporting discussions and comments

Authors of a document are able to export the list of comments received against their document. This is a requirement of the consultation report in the standards governance process so there is a record of any discussions and comments received as part of a Technical Standards Committee (TSC) consultation.

To export all discussions and comments received against a particular version of a document, i.e. a version used for a TSC consultation, please ensure the CARS document is opened up in the ‘version’ view rather than the live document:

Please then select a section on the left hand side and press the three dot button to open up the sub-menu options and in particular ‘discussions and comments’:

By clicking on the various sections you will be able to see if any discussions and comments were recorded against that version:

Where there are comments, please press ‘print’ in the top right corner to print a PDF copy of that section:

Please note you can only print discussions and comments on a section by section basis and cannot print the whole document at the same time.