Storing and developing documents in Microsoft 365 can help simplify the specification development process. The following best practices can aid in that effort. This article contains the following topics:
Keeping track of where you’ve been
Developing a specification from a shared file
Opening a document in the desktop version of Microsoft Word
Accessing a previous version of a document
Scenarios for incrementing the revision number
The process for incrementing a revision
Submitting BARB and other committee reviews
Submitting the first revision of a document to a committee for review
Submitting subsequent revisions of a document to a committee for review
Advancing a specification through the stages
Adding a new specification, enhancement, or maintenance release
Keeping track of where you’ve been
As a best practice, always have Track Changes turned on. As a Working Group addresses comments, collaborators can resolve them so that they can see what problems they’ve solved, even though all the Track Changes remain.
Developing a specification from a shared file
Prior to 2024, reviewing a specification under development involved reviewers making their own separate copy of a file with their initials appended to the file name. However, specifications and test documents are now stored on a Working Group’s SharePoint site, which uses the collaborative Microsoft 365 cloud service. This makes it possible for Working Group members to edit, review, and comment on the same document, even doing so simultaneously.
Important: You must have Word 2013 or later to use the desktop app. Otherwise, nested comment threads will be flattened, making it difficult to identify how some comments relate to one another.
If a document owner (DO) or a Working Group chooses to use the previous method of document custody where copies are attached to TP Reviews and the contributions of different reviewers are denoted by an underscore and initials in the document file name, the Technical Publications (Tech Pubs) team will continue to support this approach. However, the SIG encourages the practice of developing off of a shared document, which simplifies the process of integrating contributions and feedback from multiple contributors and reviewers.
Opening a document in the desktop version of Microsoft Word
You can open a document using your familiar desktop version of Microsoft Word from the SharePoint site without having to set up a local repository on your computer (i.e., OneDrive). This minimizes the footprint of data that is external to your organization to simply the browser cache and Word app cache. And if you need to edit a file while offline, you can open it in your Word app from the SharePoint site and sync your changes once you are reconnected. To do so, do the following (Important: You must have Word 2013 or later to use the desktop app. Otherwise, nested comment threads will be flattened):
- Navigate on your Working Group SharePoint site to the document that you want to review or edit.
- Right-click the file name of the document that you want to review or edit, hover over Open, and then click Open in app.
- Ensure Track Changes are enabled. To do so, on the Review ribbon, click Track Changes.
- Turn on AutoSave so that your edits are saved in real-time.
For more information on the different ways of editing a document in Microsoft 365, including how to set up OneDrive, see How to Edit files using the Bluetooth SIG SharePoint site.
Accessing a previous version of a document
Microsoft 365 includes strong Version History functionality, creating a new version of a document as triggered by any number of conditions (for example, when: you open a document, a change is made to a file property, someone opens a file that you already have open, 10 minutes have passed without a save, etc.). This minimizes the likelihood of data loss, and gives you the flexibility to view previous versions and even revert the document back to a particular version. For more information, see How versioning works in lists and libraries.
To access a previous version of a document from SharePoint, see View the version history of an item or file in a list or library.
To do the same in the desktop version of Microsoft Word, see View previous versions of Office files.
Submitting TP Review requests
The collaborative nature of Microsoft 365 makes it possible for a document owner (DO) to simply point to the file on SharePoint in the TP Review request rather than attaching the file. The DO can just grab a Share link from the document you want reviewed, open a TP Review request in Jira, provide any particulars they have in mind, and paste in the document link. The Technical Writer will then edit the document stored in SharePoint. If the DO prefers to actually attach the document as a copy to the TP Review and then integrate the edits after the review, that option is also available, but in terms of resolving feedback and integrating the input of multiple contributors, this approach is less efficient and more time-consuming than working from a shared file.
For more information on requesting a TP Review, see How to Create a TP Review.
Incrementing a revision
The following is adapted from the Document Naming and Marking Document (DNMD). When a document being drafted within a group has significant enough changes, the group may want to accept all changes and delete all resolved comments in order to establish a clean baseline for further development within the group.
Scenarios for incrementing the revision number
Common scenarios for incrementing the revision number include:
-
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
The process for incrementing a revision
The following workflow illustrates the process for incrementing a revision.
Figure: Process for incrementing the revision of a CR
The “_changes” document acts as a snapshot that shows all changes between two revisions of a document. For example, a “CRr06_changes” revision would show all changes across the development of the CRr06 revision up to the creation of the CRr07 revision.
Submitting BARB and other committee reviews
Much like TP Reviews, BARB and other committee reviews are simplified since all reviewers can work out of the same review file. This greatly expedites comment resolution because there’s no need to merge comments and integrate changes from multiple files.
Submitting the first revision of a document to a committee for review
When a group is ready to submit the first revision of a document to a committee for review, the group should submit a clean revision (accept all changes, and delete all comments believed to be resolved). However, for enhancements to documents that are using an integrated CR, the reviewing committee will want to see all changes since the last approved revision of the document.
Submitting subsequent revisions of a document to a committee for review
For subsequent committee reviews, the group should provide two clearly marked revisions; one showing all changes since the last committee review including how the previous round of comments were resolved, and another revision with all changes accepted and all comments believed to be resolved deleted. These documents should follow the same naming convention for as many iterations as it takes to complete the committee review.
Site organization
Working Group SharePoint sites are organized primarily by four folder levels. They are listed briefly here and described in greater detail in the subsections that follow.
Top folder level. Lists the specifications by name or, for Core, the code name of the version
Second folder level. Lists the specifications by version or, for Core, the features in that version
Third folder level. Differentiates between “Specifications” and “Test documents”.
Fourth folder level. Lists in numeric order the development stages that the specification progresses through (e.g., FRD, 0.5 or DIPD, etc.). It is in these folders that specification documents reside. For non-Core specifications that have an integrated Change Request (CR) document, the folders for those CRs are listed at this level.
Top folder level
The top folder level is intended for a given specification’s name, with its acronym/initialism framed by parentheses. In the case of the Core Specification Working Group site, the top level would be the code name for a given version.
At the bottom of the list of specifications is a folder named “zz Folder structures”. The purpose of this folder is covered later in this article in Adding a new specification, enhancement, or maintenance release.
Second folder level
The second folder level is for the various versions of a given specification with the folder named by the specification’s acronym/initialism followed by a lowercase “v” and the version number. In the case of the Core Specification Working Group site, the second folder level is a given feature’s name, with its acronym/initialism framed by parentheses. Also at this level are where media files (such as figures and MSCs) are stored. The “zz” that precedes “Media” helps to sort the media folder at the bottom of the list of specification version folders (when the list is sorted alphabetically by the “Name” column). Media files are stored at this level because the same files are usually applicable not only in the version they were introduced, but every version after that, as well.
Test Documents folder
For non-Core Working Group sites, the second folder level includes a "Test Documents" folder. This folder includes the Test documents that are applicable to all versions of a particular specification.
Media folder
Third folder level
The third folder level of a Working Group’s SharePoint site will vary depending on whether that level is for a new specification (i.e., a specification with no previous versions), an existing specification that is being enhanced with one or more new features (e.g., CSIS v1.1) a maintenance release (i.e., .Z), or an enhancement to the GATT Specification Supplement (GSS) document or Device Properties (DP) document.
New specification folder structure
The folder structure for a new specification is as follows:
Enhanced specification folder structure
The folder structure for an existing specification being enhanced with one or more new features (i.e., change requests, also known as CRs) is as follows:
The folders are numbered such that, by sorting by the "Name" column, the folders will be arranged in the order that specification progresses through the applicable stages and phases.
In the course of developing a specification or CR, related documents such as presentations or secondary research are created. These are placed in the “Related documents” folder.
Maintenance release folder structure
The folder structure for a maintenance release (i.e., a .Z) of an existing specification is as follows:
This folder structure has folders for the source specification and any applicable errata corrections. The .Z itself is stored in the "2_dX.Y.Z" folder.
In the course of developing a specification or CR, related documents such as presentations or secondary research are created. These are placed in the “Related documents” folder.
GSS/DP enhancement folder structure
The folder structure for an enhancement to either GSS or DP is as follows:
In the course of developing a specification or CR, related documents such as presentations or secondary research are created. These are placed in the “Related documents” folder.
Advancing a specification through the stages
Once a document has made it through a given development stage (e.g., 0.5), use Templates to create the document for the next stage, and save that document to the appropriate folder for that new stage (e.g., )
Adding a new specification, enhancement, or maintenance release
When you want to begin work on a new specification, enhancement, or maintenance release, you can use the folders in “zz Folder structures” to set up a folder structure for the new document.
-
On the SharePoint site, navigate to and open the “zz Folder structures” folder (Documents > zz Folder structures).
-
Right-click one of the four following folders, depending on the kind of document you are creating:
-
Copy and Rename NEW - Feature Name (Acronym). For creating a new specification that, when adopted, will be v1.0.
-
Copy and Rename ENHANCEMENT - Feature Name (Acronym). For enhancing an existing specification using a CR (Change Request).
-
Copy and Rename MAINTENANCE (.z) - Spec Name (Acronym). For creating a maintenance release of an existing specification that involves changes via errata.
-
Copy and Rename GSS or DP ENHANCEMENT. For creating a document specifying enhancements needed to the GATT Specification Supplement (GSS) document or the Device Properties (DP) document.
-
-
After right-clicking the needed folder structure, select Copy to (be careful not to select Move to) and, in the pane that opens, navigate to the location where you want to place the new folder structure. Where you place it depends on whether you are creating a new specification or an enhancement/maintenance document:
-
For a new specification, navigate to the “Documents” level of your Working Group SharePoint site, along with the other top-level specification folders.
-
For enhancement or maintenance specifications/documents, navigate to and open the parent folder of the specification that the new document will enhance or maintain (e. g., Documents > Insulin Delivery Service (IDS))
-
-
After navigating to the location to where you want to copy the folder structure, click Copy here.
Note It might take a while for SharePoint to complete the copying task. An indicator with spinning arrows on the command bar will remain present until the copy task is completed.
Clicking the indicator opens a status pane along the right edge of the browser window.
-
Once the folder copy task is complete, rename the top level folder to an appropriate name for the document that is to be developed.
Note If this is a new specification, you also need to navigate one level down and rename the “(Acronym) v1” folder.