Merge pull request #748 from opensafely-core/glossary

Make glossary entries more Airlock-specific

docs/airlock-includes/glossary.md

@@ -2,11 +2,13 @@
 *[file group]: A collection of files that share the same context and disclosure control information
 *[workspace]: a directory of files generated from the jobs that have been run on the Jobs site
 *[output file]: A file that has been added to a release request and is to be released
+*[output files]: Files that have been added to a release request and are to be released
 *[supporting file]: A file that has been added to a release request for additional information or context, and will not be released
-*[turn]: A stage of the release request process during which the request is considered to be "owned" by either the researcher (author) or the reviewer (output checker).
+*[supporting files]: Files that have been added to a release request for additional information or context, and will not be released
+*[release request turn]: A stage of the release request process during which the request is considered to be "owned" by either the researcher (author) or the reviewer (output checker).
 *[independent review]: Initial blinded review by output checkers
-*[consolidation]: Phase after independent review, when output checkers can discuss and consolidate feedback
-*[context]: Contextual description of the output files within a file group
-*[controls]: Statistical disclosure control measures that have been applied to the files within a file group
-*[vote]: An individual output checker's review of a file (i.e. approve/request changed)
-*[decision]: The combined decision on the file, based on the submitted reviews from output checkers (approved, request changes, conflicted.)
+*[review consolidation]: Phase after independent review, when output checkers can discuss and consolidate feedback
+*[file group context]: Contextual description of the output files within a file group
+*[statistical disclosure controls]: Statistical disclosure control measures that have been applied to the files within a file group
+*[file vote]: An individual output checker's review of a file (i.e. approve/request changed)
+*[file decision]: The combined decision on the file, based on the submitted reviews from output checkers (approved, request changes, conflicted.)

docs/explanation/why-airlock.md

@@ -1,6 +1,6 @@
 ## Security
 
-Airlock allows us to enforce some safety controls and policies automatically. This includes things such as the number of required reviews, independence of reviews, and ensuring that researchers who are also output checkers are not able to review their own requests.
+Airlock allows us to enforce some safety controls and policies automatically. This includes things such as the number of required reviews, independent review, and ensuring that researchers who are also output checkers are not able to review their own requests.
 
 ## User experience
 

docs/explanation/workflow-and-permissions.md

@@ -22,16 +22,16 @@ A request moves through a [series of statuses](../reference/request-states.md) d
 be "owned" by either the researcher (request author) or the output checker. 
 
 During researcher-owned statuses, the researcher can add, withdraw and update
-files on a request, and can add or edit context, controls and comments on a file 
-group. They can also choose to withdraw the request entirely.
+files on a request, and can add or edit file group context, statistical disclosure controls
+and comments on a file group. They can also choose to withdraw the request entirely.
 
 During output checker-owned statuses, output checkers can vote on files, and,
-depending on the status of the file votes, return the request to the researcher,
+depending on the status of the file decision, return the request to the researcher,
 reject it, or release files. They can also add comments and questions on file groups.
 
 Researchers and output checkers take it in turns to work on the release request.
 We refer to the change from a researcher-owned status to an output checker-owned
-status (or vice versa) as a new turn.
+status (or vice versa) as a new release request turn.
 
 For example: a researcher creates a new request and adds files to it. The release request is in status PENDING. It is "owned" by the researcher, who can continue
 to edit it.

docs/explanation/workspace-vs-request-files.md

@@ -1,7 +1,7 @@
-A **workspace file** is always the latest version of the output file created by
+A **workspace file** is always the latest version of the file created by
 a job run via the Jobs site.
 
-A **request file** is the version of the output file at the time that it was
+A **request file** is the version of the file at the time that it was
 added to a release request.
 
 When a file is added to a release request, a copy is taken of the current contents

docs/how-tos/access-airlock.md

@@ -6,7 +6,7 @@
 You will use your OpenSAFELY email address or your GitHub username to log in. These are
 the same credentials you use to access the Jobs website.
 
-However, whilst normally you log into https://jobs.opensafely.org from your browser using GitHub,
+However, whilst normally you log into <https://jobs.opensafely.org> from your browser using GitHub,
 the secure server does not have access to GitHub. So you need to use an alternate method to login to Airlock, by generating a Single Use Token via the Jobs site, and then using it on the secure
 server to log in to Airlock.
 
@@ -35,7 +35,3 @@ Log in using your GitHub username or OpenSAFELY email and the Single Use Token f
 ![Single Use Token generated on Jobs site](../screenshots/login_form.png)
 
 You should be now logged in. This login will expire after two weeks of not being used.
-
----
-
-* Next: [View workspace files](view-workspace-files.md)

docs/how-tos/create-and-submit-a-release-request.md

@@ -24,7 +24,7 @@ select the type of file (output file or supporting file).
 
 !!! note
     You can only have one active release request for a workspace at any one time. If you
-    already have an active release request, file will be added to it. If you do not have
+    already have an active release request, the file will be added to it. If you do not have
     an active release request, a new one will be created.
 
 If you added a file that you did not intend to, you can
@@ -44,7 +44,7 @@ to workspaces, and can be navigated in the same way.
 
 Output and supporting files are [differentiated in the tree by colour and icon](../reference/file-icons.md), as shown above.
 
-## Add context and controls
+## Add file group context and statistical disclosure controls
 
 Context and controls must be added to each file group before the release request
 can be submitted.
@@ -71,8 +71,3 @@ Your release request's status will transition to "Submitted", and you will no lo
 able to edit it. Output checkers will be [automatically notified](../explanation/notifications.md) that the request is ready for review.
 
 ![Submitted request](../screenshots/submitted_request.png)
-
----
-
-* Previous: [View workspace files](view-workspace-files.md)
-* Next: [Respond to a returned request](respond-to-returned-request.md)

docs/how-tos/edit-file-on-request.md

@@ -54,9 +54,3 @@ supporting file), first [withdraw the file](#withdraw-a-file) from the request a
 In order to move a file to a different file group, first [withdraw the file](#withdraw-a-file)
 from the request and then [add it again](create-and-submit-a-release-request.md#adding-files)
 with the new file group.
-
-
----
-
-* Previous: [Respond to a returned request](respond-to-returned-request.md)
-* Next: [Withdraw a release request](withdraw-request.md)

docs/how-tos/release-files.md

@@ -1,17 +1,17 @@
 When all output files in a release request have either been approved by two separate
 output checkers or withdrawn, the request can be released to the jobs site.
 
-Navigate to the request overview page; a message will indicate that independent
-review has been completed and the files can be released.
+Navigate to the request overview page; a message will indicate that
+independent review has been completed and the files can be released.
 
 ![Ready to release request](../screenshots/ready_to_release.png)
 
 !!! Note
     The option to release files is not enabled until all requested output files in a
-    release request have been approved.
+    release request have been approved, and both reviewers have submitted their reviews.
 
 
-Clicks the "Release Files" button to start the release process. 
+Click the "Release Files" button to start the release process. 
 
 The release request [transitions to the "Approved" state](../reference/request-states.md). Once all files have been uploaded to the jobs site, the
 release request will move to the "Released" state.
@@ -21,4 +21,3 @@ release request will move to the "Released" state.
 
 !!!info "Files excluded from release"
     Supporting files and withdrawn output files will not be released.
-

docs/how-tos/respond-to-returned-request.md

@@ -35,8 +35,3 @@ You can opt to respond to a request to change a file by:
 
 When you are happy that you have responded to feedback and questions, 
 [submit the request](create-and-submit-a-release-request.md#submit-the-request) again for review.
-
-
----
-* Previous: [Create and submit a release request](create-and-submit-a-release-request.md)
-* Next: [Edit a file on a request](edit-file-on-request.md)

docs/how-tos/review-a-request.md

@@ -47,14 +47,14 @@ one supporting file, all in a file group called "my-group".
 
 ![Request file tree](../screenshots/request_tree.png)
 
-## View context and controls for a file group
+## View file group context and statistical disclosure controls
 
 Click on the file group in the tree to view the file group information.
 
 ![File group](../screenshots/file_group.png)
 
-File group information contains the information about the context and controls
-that the researcher has provided for these files. 
+File group information contains the information about the file group context and 
+statistical disclosure controls that the researcher has provided for these files. 
 
 ## Review files
 
@@ -65,27 +65,26 @@ content in the browser.
 ![Request file page](../screenshots/file_review.png)
 
 The `More` dropdown also allows you to [view the file in alternative ways](../reference/view-files-alt.md), or to [view the source code](../reference/view-source-code.md) underlying
-the file. You can also [download](../reference/downloading-files.md) if required.
+the file. You can also [download](../reference/downloading-files.md) it if required.
 
 ![More dropdown](../screenshots/more_dropdown_el_request_file.png)
 
-### View context, controls and comments
+### View file group context, statistical disclosure controls and comments
 The context, controls and comments related to this file's file group can be
 viewed from the file page by clicking on the Context button.
 
 ![Context, controls and comments modal](../screenshots/context_modal.png)
 
 ### Vote on a file
 
-Use the buttons at the top of the file content to submit your vote
-for this file. Options are:
+Use the buttons at the top of the file content to submit your file vote. Options are:
 
 * **Approve** — output meets disclosure requirements and is safe to be released
 * **Request Changes** — output is not currently acceptable for release. 
 
 After approving or requesting changes to a file, the
-page will display your vote, as well as the overall decision for the
-file. You can change or reset your vote in the same way.
+page will display your file vote, as well as the overall file decision. 
+You can change or reset your vote in the same way.
 
 ![Request file post-approval](../screenshots/file_approved.png)
 
@@ -112,9 +111,9 @@ hidden from the researcher until the request is returned (or approved/released).
 ![Comments on submitted request](../screenshots/reviewed_request_comments.png)
 
 Comments that are created as private can be updated to public at a later stage.
-This can be useful during the consolidation stage, if output checkers agree that
-the comment contains a question to the researcher that they would like to ask
-without revision. 
+This can be useful during the [review consolidation](#review-consolidation) stage, 
+if output checkers agree that the comment contains a question to the researcher that
+they would like to ask without revision. 
 
 ### Submit your independent review
 
@@ -129,7 +128,7 @@ After your review has been submitted, the request status will change.
 ![After independent review submitted](../screenshots/submitted_review.png)
 
 
-### Consolidation
+### Review consolidation
 
 Once two independent reviews have been submitted, the request moves into
 "Reviewed" status. At this stage, output checkers are able to see the
@@ -170,7 +169,3 @@ Once a request has been returned, researchers will receive a
 respond to comments and re-submit the request for re-review. Review
 of re-submitted requests follows the same process described above, until
 the request is ready for release.
-
-
----
-* Next: [Release files](release-files.md)

docs/how-tos/view-workspace-files.md

@@ -21,9 +21,3 @@ From the file view, the `More` dropdown also allows you to [view the file in alt
 the file.
 
 ![More dropdown](../screenshots/more_dropdown_el.png)
-
-
----
-
-* Previous: [Accessing Airlock](access-airlock.md)
-* Next: [Create and submit a release request](create-and-submit-a-release-request.md)

docs/how-tos/withdraw-request.md

@@ -15,7 +15,3 @@ Click on the "Withdraw request" button.
 You will need to confirm that you really want to do this before proceeding.
 
 ![Withdraw request button](../screenshots/withdraw_request_modal.png)
-
-
----
-* Previous: [Edit a file on a request](edit-file-on-request.md)

docs/index.md

@@ -4,14 +4,14 @@ Airlock is a service running inside the secure environment to allow researchers
 view output files, create release requests, and for output checkers to review and
 release these requests.
 
-Researchers use the Airlock UI to view their workspace files, create a new release request, add their files to the release request, provide context information and
+Researchers use the Airlock UI to view their workspace files, create a new release request, add their files to the release request, provide file group context information and
 description of applied statistical disclosure controls, and submit the files for review.
 
 Output checkers review the files requested for release, and approve or request changes for
 each one. Once a full review of all files has been completed by two output checkers and all
-filees are approved, an output checker can release the files to the Jobs site.
+files are approved, an output checker can release the files to the Jobs site.
 
-Airlock allows us to enforce some safety controls and policies automatically. This includes things such as the number of required reviews, independence of reviews, and ensuring that researchers who are also output checkers are not able to review their own requests.
+Airlock allows us to enforce some safety controls and policies automatically. This includes things such as the number of required reviews, independent review, and ensuring that researchers who are also output checkers are not able to review their own requests.
 
 
 ## Accessing Airlock

docs/reference/terms-and-definitions.md

@@ -34,7 +34,7 @@ into logical groups, in order to help the output checker understand the request.
 Supporting files should be placed in the same file group as the output file they support.
 
 
-## Context
+## File Group Context
 Contextual description of what data is contained in the output files within a file group
 explaining e.g.:
 
@@ -45,12 +45,12 @@ explaining e.g.:
 - relationship to other data/tables which through combination may introduce secondary disclosive risks.
 
 
-## Controls
+## Statistical Disclosure Controls
 
 Description of statistical disclosure control measures (e.g. rounding/suppression) that have been
 applied to the files within a file group.
 
-## Turn
+## Release Request Turn
 
 A stage of the release request process during which the request is considered to be "owned"
 by either the researcher (author) or the reviewer (output checker). 
@@ -72,7 +72,7 @@ agree.)
 Each time a release request is submitted for review, it is initially reviewed independently by two output checkers. At this stage, output checkers are not aware of the status of other 
 reviews, and cannot see comments made by other output checker.
 
-## Consolidation
+## Review consolidation
 
 After output checkers have both completed their independent review, there is a phase of 
 consolidation, where they can collaborate and determine the questions and feedback that

mkdocs.yml

@@ -12,9 +12,9 @@ docs_dir: docs
 site_dir: mkdocs_build
 
 nav:
-  - About: index.md
+  - About Airlock: index.md
   - How-to guides:
-    - how-tos/index.md
+    - How-to guides: how-tos/index.md
     - How to access and log in Airlock: how-tos/access-airlock.md
     - For researchers:
       - View output files in a workspace: how-tos/view-workspace-files.md
@@ -26,13 +26,13 @@ nav:
       - Review a request: how-tos/review-a-request.md
       - Release files: how-tos/release-files.md
   - Explanation: 
-    - explanation/index.md
+    - Explanation: explanation/index.md
     - Why Airlock?: explanation/why-airlock.md
     - How does a workspace file differ from a request file?: explanation/workspace-vs-request-files.md
     - Workflow and permissions: explanation/workflow-and-permissions.md
     - Notifications: explanation/notifications.md
   - Reference:
-    - reference/index.md
+    - Reference: reference/index.md
     - reference/terms-and-definitions.md
     - File icons and colours: reference/file-icons.md
     - Alternative ways to view files: reference/view-files-alt.md