From 21823e339597a6bf8728f0ea4bf39e9bb5de8a0f Mon Sep 17 00:00:00 2001 From: Becky Smith Date: Wed, 22 Jan 2025 11:33:34 +0000 Subject: [PATCH 1/3] Make glossary entries more Airlock-specific This will prevent the airlock glossary being triggered in the main docs for commonly-used terms (e.g. "vote") used in a non-Airlock context. --- docs/airlock-includes/glossary.md | 14 ++++++----- docs/explanation/why-airlock.md | 2 +- docs/explanation/workflow-and-permissions.md | 8 +++--- .../explanation/workspace-vs-request-files.md | 4 +-- docs/how-tos/access-airlock.md | 2 +- .../create-and-submit-a-release-request.md | 4 +-- docs/how-tos/release-files.md | 8 +++--- docs/how-tos/review-a-request.md | 25 +++++++++---------- docs/index.md | 6 ++--- docs/reference/terms-and-definitions.md | 8 +++--- 10 files changed, 41 insertions(+), 40 deletions(-) diff --git a/docs/airlock-includes/glossary.md b/docs/airlock-includes/glossary.md index 488281bf..d7caf860 100644 --- a/docs/airlock-includes/glossary.md +++ b/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]: File 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.) diff --git a/docs/explanation/why-airlock.md b/docs/explanation/why-airlock.md index cdb88d6a..442c239f 100644 --- a/docs/explanation/why-airlock.md +++ b/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 diff --git a/docs/explanation/workflow-and-permissions.md b/docs/explanation/workflow-and-permissions.md index 302f8eaa..b0ec9c53 100644 --- a/docs/explanation/workflow-and-permissions.md +++ b/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. diff --git a/docs/explanation/workspace-vs-request-files.md b/docs/explanation/workspace-vs-request-files.md index e5badeae..c5fcfd73 100644 --- a/docs/explanation/workspace-vs-request-files.md +++ b/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 diff --git a/docs/how-tos/access-airlock.md b/docs/how-tos/access-airlock.md index 2105e71b..f8fbbbc2 100644 --- a/docs/how-tos/access-airlock.md +++ b/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 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. diff --git a/docs/how-tos/create-and-submit-a-release-request.md b/docs/how-tos/create-and-submit-a-release-request.md index 76800009..a342673d 100644 --- a/docs/how-tos/create-and-submit-a-release-request.md +++ b/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. diff --git a/docs/how-tos/release-files.md b/docs/how-tos/release-files.md index 623b74f6..2cbe1c22 100644 --- a/docs/how-tos/release-files.md +++ b/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. diff --git a/docs/how-tos/review-a-request.md b/docs/how-tos/review-a-request.md index b16493e6..31d1a850 100644 --- a/docs/how-tos/review-a-request.md +++ b/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,11 +65,11 @@ 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. @@ -77,15 +77,14 @@ viewed from the file page by clicking on the Context button. ### 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 diff --git a/docs/index.md b/docs/index.md index 2baf46dd..88694613 100644 --- a/docs/index.md +++ b/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 diff --git a/docs/reference/terms-and-definitions.md b/docs/reference/terms-and-definitions.md index e089fac9..3aceb3c3 100644 --- a/docs/reference/terms-and-definitions.md +++ b/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 From 5a5d99ad741212e8b66815a82e1ef1f4914a4eef Mon Sep 17 00:00:00 2001 From: Becky Smith Date: Wed, 22 Jan 2025 11:39:56 +0000 Subject: [PATCH 2/3] Update navigation Remove unused footer navigation - this is handled by the navigation theme defined in mkdocs.yml. Also updates some section titles (so that the navigation shows e.g. "Reference" instead of "Index" --- docs/how-tos/access-airlock.md | 4 ---- docs/how-tos/create-and-submit-a-release-request.md | 5 ----- docs/how-tos/edit-file-on-request.md | 6 ------ docs/how-tos/release-files.md | 1 - docs/how-tos/respond-to-returned-request.md | 5 ----- docs/how-tos/review-a-request.md | 4 ---- docs/how-tos/view-workspace-files.md | 6 ------ docs/how-tos/withdraw-request.md | 4 ---- mkdocs.yml | 8 ++++---- 9 files changed, 4 insertions(+), 39 deletions(-) diff --git a/docs/how-tos/access-airlock.md b/docs/how-tos/access-airlock.md index f8fbbbc2..0522d799 100644 --- a/docs/how-tos/access-airlock.md +++ b/docs/how-tos/access-airlock.md @@ -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) diff --git a/docs/how-tos/create-and-submit-a-release-request.md b/docs/how-tos/create-and-submit-a-release-request.md index a342673d..b7141afd 100644 --- a/docs/how-tos/create-and-submit-a-release-request.md +++ b/docs/how-tos/create-and-submit-a-release-request.md @@ -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) diff --git a/docs/how-tos/edit-file-on-request.md b/docs/how-tos/edit-file-on-request.md index c527f146..10e54766 100644 --- a/docs/how-tos/edit-file-on-request.md +++ b/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) diff --git a/docs/how-tos/release-files.md b/docs/how-tos/release-files.md index 2cbe1c22..2113e87d 100644 --- a/docs/how-tos/release-files.md +++ b/docs/how-tos/release-files.md @@ -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. - diff --git a/docs/how-tos/respond-to-returned-request.md b/docs/how-tos/respond-to-returned-request.md index f00a44b7..7ddfa22d 100644 --- a/docs/how-tos/respond-to-returned-request.md +++ b/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) diff --git a/docs/how-tos/review-a-request.md b/docs/how-tos/review-a-request.md index 31d1a850..1113d47f 100644 --- a/docs/how-tos/review-a-request.md +++ b/docs/how-tos/review-a-request.md @@ -169,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) diff --git a/docs/how-tos/view-workspace-files.md b/docs/how-tos/view-workspace-files.md index fbfc4804..1f3effad 100644 --- a/docs/how-tos/view-workspace-files.md +++ b/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) diff --git a/docs/how-tos/withdraw-request.md b/docs/how-tos/withdraw-request.md index 9f88cf61..ba2020f2 100644 --- a/docs/how-tos/withdraw-request.md +++ b/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) diff --git a/mkdocs.yml b/mkdocs.yml index a7cd7470..f24f1b0b 100644 --- a/mkdocs.yml +++ b/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 From 52087a35d0cafbdfa1f447b870772367d1972b33 Mon Sep 17 00:00:00 2001 From: Becky Smith Date: Thu, 23 Jan 2025 12:59:23 +0000 Subject: [PATCH 3/3] Update docs/airlock-includes/glossary.md Co-authored-by: Tom Ward --- docs/airlock-includes/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/airlock-includes/glossary.md b/docs/airlock-includes/glossary.md index d7caf860..e3303893 100644 --- a/docs/airlock-includes/glossary.md +++ b/docs/airlock-includes/glossary.md @@ -2,7 +2,7 @@ *[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]: File that have been added to a release request and are 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 *[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).