Address PR comments.

Observatory-Control-System/BLOCKS/block-jira-project-workflow.rst

@@ -28,41 +28,77 @@ BLOCK JIRA Workflow
 The Rubin Observatory uses observing blocks to design, plan, execute, and track tasks at the summit which require data taking.
 These tasks range from pure engineering (e.g. closed-dome TMA velocity tests) to science-driven surveys. 
 In most cases, the planning and execution of such tasks must take place on a much shorter timescale than the analysis of the data that is collected, necessitating a separate JIRA project and workflow. 
-This workflow is captured in the BLOCK Project, and described in detail here. 
+
+To facilitate this workflow, we have created the `BLOCK JIRA Project <https://rubinobs.atlassian.net/jira/software/c/projects/BLOCK/boards/228>`_ , described in detail here. 
 
 .. figure:: _static/BLOCK_Jira_workflow.png
     :name: BLOCK Jira Project Workflow
     :align: center
     :width: 480
 
-    A block diagram of the workflow contained in the BLOCK Jira project.
+    A block diagram of the workflow used by the BLOCK Jira project.
 
 BLOCK Ticket Roles and Workflow
 ===============================
 
-BLOCK tickets are heavily relied on during both the task planning and task execution phases, 
-and provide a central point of communication between stakeholders and the summit crew. 
+BLOCK tickets are heavily relied on during both the task planning and task execution phases, and provide a central point of communication between stakeholders and the summit crew. 
 Since nearly all groups across the observatory are stakeholders in the tests that are carried out at the summit, clear roles and expectations must be defined for how the JIRA BLOCK tickets are used. 
 Here we define the various roles and their expectations, and present a brief overview of the BLOCK Ticket workflow. 
 
 
 Roles and Responsibilities
 --------------------------
-In the JIRA issues, there are only two formal roles defined: Proposer and Assignee. 
+In the JIRA issues, there are only two formal roles assigned: Proposer and Assignee. 
 
 **Proposer**
 ^^^^^^^^^^^^
-The Proposer is the stakeholder requesting the observing task. 
-They are chiefly responsible for the initial ticket submission, including providing links to supporting materials, and the final ticket sign-off (see Transitioning to Done). 
-They are expected to work closely with the Assignee during the Preparation phase, but are not expected to be involved in planning when a task will take place or during the task execution (unless otherwise required). 
-Anyone can take the role of Proposer as long as they are knowledgeable in the task requirements and completion criteria. 
+The Proposer is typically a stakeholder interested in the observing task's outcomes.
+Key responsibilities include:
+
+- **Initial Ticket Submission**
+
+  - They are chiefly responsible for the initial ticket submission, providing a detailed description of the observing task.
+  - Includes necessary supporting materials, such as links to relevant tickets (e.g., SITCOM, LVV) or documentation on Confluence pages.
+
+- **Collaboration during Preparation**
+
+  - Collaborates with the Assignee during the Preparation phase to ensure all task requirements and completion criteria are clearly understood.
+
+- **Final Verification and Sign-Off**
+
+  - Review the outcomes after task execution to ensure objectives have been met.
+  - Verifies and confirms task completion, reviewing any related data or results.
+  - Transitions the ticket to "Done" to officially close the issue once satisfied with the task completion.
+
+.. note::
+    Anyone can take the role of Proposer as long as they are knowledgeable in the task requirements and completion criteria.
 
 **Assignee**
 ^^^^^^^^^^^^
-The Assignee is the member of the Commissioning Science team expected to oversee the task during the preparation and execution phase. 
-They are expected to collaborate with the Proposer during task preparation, and are directly responsible for ensuring the task is Ready for execution at the summit. 
-They are expected to track task progress and advocate for task completion during the task planning meetings when necessary. 
+The Assignee is a member of the Commissioning Science team, responsible for overseeing the task from preparation through execution.
+Responsibilities include:
+
+
+- **Task Preparation and Planning**
+
+  - Collaborates with the Proposer to understand task requirements during early preparation stages.
+  - Prepares the task for execution, including finalizing methodological details and setting up necessary components.
 
+- **Marking as Ready**
+
+  - Marks the ticket as "Ready" once all preparations are complete and validated, indicating it is prepared for execution.
+
+- **Advocacy and Tracking**
+
+  - Advocates for the task in planning meetings to ensure it is prioritized and scheduled.
+  - Tracks the task progress through to execution, addressing any issues that may arise.
+
+- **Role during Execution**
+
+  - Ensures everything is in place for successful execution, although the actual execution is typically done by an Observing Specialist.
+
+**Un-assigned Roles**
+^^^^^^^^^^^^^^^^^^^^^
 In addition, there is the role of planning the tasks for execution once they have been set to READY. 
 This is expected to be carried out in accordance with the priority assigned to the task by the Commissioning Science team. 
 While awaiting execution, tickets will remain in the READY state and their priority may be updated as needed.
@@ -74,13 +110,14 @@ However, they do hold the final say of whether a task can be executed on the sum
 
 Overview of Workflow
 --------------------
-Here we provide a bulleted list illustrating an example workflow. 
+An example workflow of the interactions between the roles could look like
 
 * Stakeholder requires an observing task to be completed at the summit, and describes the task in an LVV ticket, SITCOM ticket, or Confluence page. 
-* Stakeholder proposes a new BLOCK Jira ticket, providing links to supporting material and assuming responsibility of Proposer. 
+* Stakeholder proposes a new BLOCK Jira ticket, providing links to supporting material and assuming responsibility of Proposer. The stakeholder requiring an observing task does not always need to author the BLOCK Jira ticket, that responsibility can be shared with someone more knowledgeable with JIRA or the workflow processes as long as they are in close collaboration with the stakeholder. 
 * New BLOCK Jira ticket is reviewed by Commissioning Science team during one of the regular, weekly planning meetings, and accepted/rejected for scheduling. 
 * New BLOCK Jira ticket is given a priority for scheduling and a Commissioning Scientist is Assigned the ticket, taking on the responsibility of Assignee. 
 * Proposer and Assignee work together to prepare BLOCK ticket for execution.
+* Assignee performs test and validation of observing block instructions using the test stands where appropriate.
 * BLOCK ticket is marked as READY by Assignee, and added to the queue of tasks to be executed. 
 * BLOCK ticket is planned for execution at the summit by the night planner. 
 * BLOCK ticket is executed at the summit by Observing Specialist.
@@ -91,7 +128,8 @@ BLOCK Ticket Requirements
 =========================
 
 In addition to the standard JIRA ticket fields, proposers are also required to supply the following information: 
-* Component - either be MainTel or AuxTel
+
+* Component - either MainTel or AuxTel
 * Original Time Estimation - selectable in the More Fields section of the ticket. 
 * Links to supporting material either tickets (e.g. SITCOM/LVV) or confluence pages
 
@@ -106,7 +144,8 @@ BLOCK descriptions walk a very fine line between having just enough information
 They should not read like a novel, too much information is likely to get lost at the pace with which execute at night. 
 They must contain the minimum set of instructions needed to carry out the complete observing task. 
 
-We recommend that at a minimum the description section must contain:
+At a minimum the description section should contain:
+
 * Description, high-level overview of test
 * Pre-conditions/requirements to run test, including system status
 * Environmental Constraints on test (e.g. observing conditions/time)
@@ -115,26 +154,27 @@ We recommend that at a minimum the description section must contain:
 
 Make use of the formatting options to provide separation between sections and make this information easy to find. 
 
-Here we provide a complete example. 
-
 **Description**
 Include a brief, 1-2 sentence overview of the test here. 
 
 **Pre-conditions**
 These should be provided as a list or short descriptive section. Examples include
+
 * MTRotator in DISABLED state
 * EUI Recording enabled
 * TMA Settings set to 40% max
 
 **Environmental Constraints**
 This section should include any time or condition constraints e.g. 
+
 * Atmospheric Seeing less that 1.5 arcseconds.
 * Photometric conditions required. 
 * Test must be executed between 12:00 and 01:00 local time. 
 
 **Test Execution Instructions**
 This section should be written to be as direct as possible and contain the minimum necessary instruction to execute the test. 
 For example, if a JSON BLOCK has been prepared to execute the test, this should be something like:
+
 * Run the JSON BLOCK using the add_block.py SAL Script with the following configuration - id: BLOCK-123
 
 If the test execution involves a series of SAL Scripts, provide the script names and all required configurations. 
@@ -148,6 +188,10 @@ This section should provide some context/expectations of what will happen during
 This will allow the users to evaluate the progress and success of the test without having to search and parse the detailed code. 
 It is  recommended to provide this as a bulleted list of steps, rather than in paragraph form, to make it easier to read. 
 
+.. note::
+    We are in the process of adopting a new standard procedure to include a Test Case in place of the Test Execution Instructions and Description of test steps.
+    This document will be updated when the workflow is finalized. 
+
 BLOCK Ticket States and Transitions
 ===================================
 
@@ -236,6 +280,74 @@ This transition should be rare.
 It is reserved for cases when a job is erroneously transitioned to a completed state, or a later analysis of the observing task deems it was not satisfactorily completed. 
 The ticket is then transitioned to Proposed so it can be prepared and prioritized accordingly by a Commissioning Science Team.
 
+BLOCK Ticket Checklist
+======================
+
+To summarize all of the above, we provide a checklist focused on the steps needed by each role for reference. 
+
+Proposer Checklist
+------------------
+
+Initial Ticket Submission
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Identify the need for an observing task.
+- Draft a clear description of the observing task, including high-level objectives and specific requirements.
+- Gather and attach supporting materials such as relevant tickets (SITCOM, LVV) or documentation on Confluence pages.
+- Create and submit the BLOCK Jira ticket.
+- Provide an original time estimation for the task execution, including preparation and any additional time for configuration or logging.
+
+Collaboration during Preparation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Review and discuss the preparation details with the Assignee to ensure all task requirements are clearly understood.
+- Provide any additional information or clarifications needed by the Assignee.
+
+Final Verification and Sign-Off
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Review the outcomes of the executed task to ensure all objectives have been met.
+- Verify the completeness and accuracy of the data or results collected.
+- Provide final sign-off and transition the ticket to "Done" if satisfied with the task completion.
+- Initiate re-evaluation if the task outcomes do not meet the expected criteria, by transitioning the ticket back to "Proposed."
+
+Assignee Checklist
+------------------
+
+Task Preparation and Planning
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Receive and review the BLOCK ticket once assigned by the Commissioning Science team.
+- Collaborate with the Proposer to fully understand the task requirements and expectations.
+- Plan the detailed preparation of the task, including method selection (e.g., JSON BLOCK, SAL Script) and setup.
+- Prepare and configure all necessary components or settings for the task.
+
+Marking as Ready
+^^^^^^^^^^^^^^^^
+
+- Conduct a thorough final check to ensure all preparations meet the required standards and are fully operational.
+- Validate all configurations and preconditions for the task execution.
+- Mark the BLOCK ticket as "Ready" indicating readiness for execution.
+
+Advocacy and Tracking
+^^^^^^^^^^^^^^^^^^^^
+
+- Advocate for the task in planning meetings to ensure it is scheduled based on its priority.
+- Track the status of the task and update its priority if necessary.
+- Ensure the task is added to the execution plan and adequately prepared for execution at the summit.
+
+Role during Execution
+^^^^^^^^^^^^^^^^^^^^^
+
+- Provide necessary instructions or clarifications to the Observing Specialist or execution team at the summit.
+- Monitor the execution of the task and be available to address any issues that may arise during the execution phase.
+
+Observing Specialist Checklist
+------------------------------
+
+- Review the task details and any specific instructions before execution.
+- Execute the observing task as planned during the scheduled night.
+- Report any issues or deviations during execution to the Assignee. 
 
 Contact Personnel
 ^^^^^^^^^^^^^^^^^