Upon transitioning to a new way of authoring and reviewing specification documents in SharePoint, the Alignment and Process Improvement Committee (APIC), in consultation with BARB, developed a methodology for how to move documents through its stages with its accompanying revisions and reviews.

Methodology principles

Three key characteristics to this methodology are worth noting, because they set the course for how the revision and review workflow is laid out.

• Working document. The document is “live” and “version-less”.
• Revisions (r00, r01, etc.). Function as “snapshots”.
• Document compares. Identify changes between two revisions of the same document.

The following subsections describe these in greater detail.

Working document

The following characterize the working document:

• The working document is always the document of record and contains the most recent changes and comments.
• It resides on SharePoint where it is always “live” (as opposed to residing offline on the document owner’s (DO) computer).
• Anyone who contributes to the document does so from its location on SharePoint, whether using a browser or opening it in the desktop Word app from SharePoint or OneDrive. Copies of documents are not to be downloaded and worked on.
• As the working document moves through a specification development stage (i.e., DIPD/0.5, FIPD/0.7, 0.9/CR), its file name does not change and is not identified in the file name as being a particular revision or version. The document is, in this sense, versionless.
• That being stated, the Version field on the title page does indeed reflect whatever the latest revision number is. Likewise, the Version History table of the document contains a running record of revisions and their respective change summaries.

Revisions

The following characterize the revisions:

• Revisions function as snapshots.
• They are taken at different milestones such as an IOP event, committee review, TP review, etc.
• Once created, revisions are archived for future reference and are never edited; they are read only.
• They show track changes and are used for historical purposes to indicate what has changed between revisions.
• Changes during a revision are documented in individual rows of the Version History table.
• Used for doing document compares, which are particularly helpful for committee reviews and approvals.
• Common scenarios for incrementing the revision number:
  • After incorporating internal Working Group feedback regarding a particular issue, erratum, or feature.
  • After an iterative cycle of TP Review/Technical Review and the subsequent comment resolution.
  • After incorporating committee and Legal feedback.
  • After posting a Public Release draft.

Document compares

The following characterize document compares:

• They are generated using Microsoft Word to identify changes between two revisions of the same document, or between the working document itself and a previous revision.
• They are used as a reference when a group (committee, TP, Legal, etc.) has seen the document before and the document is going for a new round of reviews. This allows the group to only review what was added or changed since the last time they reviewed the document.

The workflow

This section consists of the workflow diagram and the procedures that are involved in moving a document through that workflow.

Workflow diagram

Diagram 1: SharePoint-based document authoring/revision/review cycle

* If the DO and Working Group need to continue to work on the document during a review, they can follow a secondary workflow that begins at this point in the workflow. See Continuing work on the working document during a review.

Workflow procedures

The following procedures describe the workflow for advancing a SharePoint-based specification toward and through a review cycle. The workflow can be broken down into the following subtasks:

• Create and develop the CR
• Prep the working document for a snapshot (i.e., revision)
• Create the snapshot
• Prep the working document for review
• Request a review and resolve comments when complete

For the purpose of illustration, for a specification that has just started the CR stage, the workflow would proceed through these subtasks as follows:

Create and develop the CR

1. At the beginning of a development stage (e.g., CR), The document owner (DO) creates the CR document in accordance with the Specification Management Process Document (SMPD). The file name of the document follows the conventions of the Document Naming and Marking Document (DNMD).
2. The DO and Working Group works on the document, adding and revising content as needed and adding comments.
3. The CR document reaches a point when it is ready to go to review outside the Working Group (committee, TP, Legal, etc.).

Prep the working document for a snapshot (i.e., revision)

1. Just prior to creating a snapshot, the DO updates the Version History table with the current revision number and adds a change summary of what has changed in the document from the previous revision.
2. If the Version value on the title page does not reflect whatever the latest revision number is, the DO updates it.

Create the snapshot

1. To capture the state of the document prior to the review, the DO creates a snapshot in the form of a revision. The DO does so by clicking File > Save a Copy, and appends to the file name r01 (e.g., HFP_CallForwarding_CRr01.docx).
2. After saving the file, the DO makes the snapshot read only. To do so, the DO clicks Review > Protect > Restrict Editing. The Restrict Editing pane appears. Under 2. Editing restrictions, the DO checks Allow only this type of editing in the document and verifies that the selected option is No changes (Read only). The DO then clicks Yes, Start Enforcing Protection. The DO then saves the document and closes it.
3. The DO navigates to the location of the document—either on SharePoint or locally on OneDrive. If an Archive folder isn’t present, the DO creates a new folder, names it Archive, and moves the newly created snapshot into the Archive folder.

Prep the working document for review

1. The DO increments the Version value on the title page.
2. To minimize clutter for reviewers from previously-reviewed revisions, the DO accepts all Tracked Changes and deletes all resolved comments. The DO will want to be careful not to delete any active comment threads in the document.

Request a review and resolve comments when complete

1. DO creates a Jira review request and includes links to the working document and the snapshot.
   Notes
   
   • In the case of a committee review where the committee has seen the same document during a previous review within this current stage, the DO can contact BSTS to create a document compare showing what has changed since the last review.
   • In the case of a TP Review, BSTS locks the file.
   • During a review, the working document is to be considered “locked” and, as a best practice, it is preferrable that no additional DO or Working Group development takes place until the review is complete and the review comments have been resolved.
   • If ongoing development of the working document during the review is unavoidable, a mechanism within the workflow has been established to address this need. See Continuing work on the working document during a review.
2. Reviewers review the document.
   • In the case of a committee review, reviewers provide feedback as comments in the working document rather than editing the content directly.
   • In the case of a TP Review, as applicable, BSTS adds errata/issue numbers as comments where the changes appear in the working document. BSTS also unlocks the document at the conclusion of the review.
3. Once the review is over, the Working Group resolves the comments and continues to develop the document until it reaches a point where it makes sense to the DO and the Working Group to create another snapshot, in which case the DO would want to consult Prep the working document for a snapshot (i.e., revision).

Continuing work on the working document during a review

While it is not recommended, there might be cases when a Working Group needs to keep authoring the working document even while it is in review. To accommodate this, the DO and Working Group can make use of this secondary workflow, which they can follow once the review begins. The secondary workflow is as follows:

Diagram 2: Continuing work on the working document during a review

If the DO or Working Group have questions about this secondary workflow or need assistance, they can receive support from the Tech Pubs technical writer or editor who supports the Working Group. In the absence of a specific contact, the DO or Working Group can send an email to specreview-editor@bluetooth.org.

Reviewer best practices for a SharePoint-authored document

• In SharePoint, open the document to review by right-clicking the file name of the document > Open > Open in app.
• Do not check out the file.
• Do not make a copy of the document and/or add your initials to the file name. All work takes place in the working document.
• Add your feedback using the Comments feature (in Microsoft Word, Review > New Comment).
• Do not make edits directly in the document; use the Comments feature.
• In the Jira review request, once you have completed your review, mark your review task as either Changes Required - Review Completed or No Changes Required - Review Completed.