improve formatting.

Observatory-Control-System/BLOCKS/BLOCKS-index.rst

@@ -13,19 +13,23 @@
 .. To reference a label that isn't associated with an reST object such as a title or figure, you must include the link an explicit title using the syntax :ref:`link text <label-name>`.
 .. An error will alert you of identical labels during the build process.
 
-#################################################
+######
 BLOCKS
-#################################################
+######
 
 .. This section should provide a brief, top-level description of the page.
 
 .. _BLOCKS:
 
-BLOCKS2  
+.. _BLOCK-Jira-project:
+
+BLOCK Jira Project
 ==================
 
+A description of the BLOCK Jira project and associated ticket workflow. 
+
 .. toctree::
    :glob:
    :titlesonly:
 
-   BLOCKS2/BLOCKS2-index.rst
+   block-jira-project-workflow.rst

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

@@ -19,7 +19,7 @@
 .. To reference a label that isn't associated with an reST object such as a title or figure, you must include the link an explicit title using the syntax :ref:`link text <label-name>`.
 .. An error will alert you of identical labels during the build process.
 
-.. _BLOCK-observations:
+.. _BLOCK-Jira-Workflow:
 
 ###################
 BLOCK JIRA Workflow
@@ -30,81 +30,105 @@ These tasks range from pure engineering (e.g. closed-dome TMA velocity tests) to
 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. 
 
-BLOCK Jira Project Description
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 .. figure:: _static/BLOCK_Jira_workflow.png
     :name: BLOCK Jira Project Workflow
-    :width: 621
-    :height: 422
+    :align: center
+    :width: 480
 
     A block diagram of the workflow contained in the BLOCK Jira project.
 
-End states
-------------
-The end states are the ultimate destination of a reported ticket.
-When a ticket reaches one of these states, is will no longer be considered for scheduling.
-We start by explaining these states because they are referenced throughout the remainder of the document, specifically when describing state transitions.
+BLOCK Ticket States and Transitions
+===================================
 
-- ``Done``: All work required to complete the observing block has been Done. There is no current plan to repeat the task. 
-
-- ``Invalid``:  The requested observing block is no longer valid, was filed by mistake, or has been superseded by another block or other events.
-
-There are multiple ways that tickets reach these states, which are explained in the sections below.
-The ``Invalid`` and ``Duplicate`` state is special because it can be transitioned to from any active state in the workflow.
-
-Both ``Invalid`` and ``Done`` allow transition out of these states, which is to return to the ``Proposed`` state and start the workflow over again.
-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.
+The JIRA workflow for BLOCK Tickets has been designed to facilitate task preparation, planning, and execution. 
+BLOCK tickets provide the direct link between an observing task Proposer and the team that will be responsible for executing the task at the summit. 
+Here we describe the individual states and their allowed transitions. 
+In each section, we identify the work expected to be done in each state and the party responsible. 
 
 Active states
 -------------
 This section describes each of the active states as well as any transition from that state to another.
 
-- ``Proposed:`` This is the default state that a ticket enters when it is initially filed. 
-  By default, the ticket is left unassigned. 
-  The Commissioning Scientist team is responsible for the initial assessment and assignment of the observing task. 
-  New ticket in the ``Proposed`` state will be reviewed and assigned on a weekly basis (or twice weekly) during one of several planning meetings.
-  The reporter is not responsible for alerting anyone to new ticket creation, but a message on the #sitcom-observing-blocks slack channel is recommnded. 
-  Once the ticket has been assigned to a member of the Commissioning Science team, it will be transitioned to ``Preparation``.
+**Proposed**
+^^^^^^^^^^^^
+This is the default state that a ticket enters when it is initially filed. 
+By default, the ticket is left unassigned. 
+The Commissioning Scientist team is responsible for the initial assessment and assignment of the observing task. 
+New ticket in the Proposed state will be reviewed and assigned on a weekly basis (or twice weekly) during one of several planning meetings.
+The reporter is not responsible for alerting anyone to new ticket creation, but a message on the #sitcom-observing-blocks slack channel is recommended. 
+Once the ticket has been assigned to a member of the Commissioning Science team, it will be transitioned to Preparation.
 
-    - *Transition to* ``Preparation``: An initial assessment of the observing task will be done during the weekly planning meeting by the Commissioning Science team. 
-      This initial assessment will include a discussion of work needed to prepare the task, a decision on the priority of the task, and an assignment to a member of the Commissioning Science team for preparation.  
-      Once the ticket has been assigned it can be transitioned to the ``Preparation`` state. 
+*Transition to Preparation*: An initial assessment of the observing task will be done during the weekly planning meeting by the Commissioning Science team. 
+This initial assessment will include a discussion of work needed to prepare the task, a decision on the priority of the task, and an assignment to a member of the Commissioning Science team for preparation.  
+Once the ticket has been assigned it can be transitioned to the Preparation state. 
 
 
-- ``Preparation``: This state describes a task that is currently being prepared for execution at the summit. 
+**Preparation**
+^^^^^^^^^^^^^^^
+
+This state describes a task that is currently being prepared for execution at the summit. 
 
-  At this stage, the assignee is expected to work with the proposer to prepare the task for execution at the summit. 
-  The work required in this state includes:
-  - A decision on the best method to execute the observing block (e.g. JSON BLOCK, SAL Script, etc) by the Proposer and Assignee. 
-  - Preparation of the observing task (e.g. write a new JSON BLOCK) by the Proposer and Assignee.   
-  - Testing and validation of the observing task to the extent possible on one of the Test Stands by the Assignee.   
-  - A review of the ticket description for any missing instructions or information (see section below) by the Assignee. 
-  - Deployment of any necessary components/changes at the Summit (e.g. JSON BLOCK) by the Assignee. 
+At this stage, the assignee is expected to work with the proposer to prepare the task for execution at the summit. 
+
+The steps expected to be completed in this state include:
+
+* A decision on the best method to execute the observing block (e.g. JSON BLOCK, SAL Script, etc) by the Proposer and Assignee. 
+* Preparation of the observing task (e.g. write a new JSON BLOCK) by the Proposer and Assignee.   
+* Testing and validation of the observing task to the extent possible on one of the Test Stands by the Assignee.   
+* A review of the ticket description for any missing instructions or information (see section below) by the Assignee. 
+* Deployment of any necessary components/changes at the Summit (e.g. JSON BLOCK) by the Assignee. 
+
+*Transition to Ready*: Once all of the steps above have been completed, the Assignee is responsible for transitioning the ticket to Ready. 
+
+*Transition to Proposed*: After initial assignee assessment if the work cannot be completed by the assignee in a timely manner in accordance with the observing task priority, it can be returned to Proposed for re-assignment. 
 
-  - *Transition to* ``Ready``: Once all of the steps above have been completed, the Assignee is responsible for transitioning the ticket to Ready. 
+**Ready**
+^^^^^^^^^
+This state is reserved for observing tasks which have been prepared, tested, reviewed, and deployed at the summit and are ready for execution.
 
-  - *Transition to*  ``Proposed``: After initial assignee assessment if the work cannot be completed by the assignee in a timely manner in accordance with the observing task priority, it can be returned to ``Proposed`` for re-assignment. 
+While in the Ready state, a task can be added to the plan at any time. 
+Tasks will be planned for observation in accordance with the priority they were assigned in the Proposed state. 
+A review of the tasks which are in the Ready state is to be carried out as part of the regular Commissioning Science planning meetings. 
 
-- ``Ready``: This state is reserved for observing tasks which have been prepared, tested, reviewed, and deployed at the summit and are ready for execution.
+The steps expected to be completed in this state include:
 
-    While in the ``Ready`` state, a task can be added to the plan at any time. 
-    Tasks will be planned for observation in accordance with the priority they were assigned in the ``Proposed`` state. 
-    A review of the tasks which are in the ``Ready`` state is to be carried out as part of the regular Commissioning Science planning meetings. 
-    The work required in this state includes:
-    - Planning of the task for execution by the Commissioning Science team. 
-    - Execution of the task at the Summit.
-    - Review of the data and assessment of task completion by the Proposer and Assignee. 
+* Planning of the task for execution by the Commissioning Science team. 
+* Execution of the task at the Summit.
+* Review of the data and assessment of task completion by the Proposer and Assignee. 
 
-    - *Transition to* ``Preparation``: If an issue is found with the observing task after it has been transitioned to ``Ready``, it may be transitioned back to ``Preparation``.
-      This transition could be triggered by either the Assignee, the Proposer, or the user responsible for executing the task on the Summit. 
+*Transition to Preparation*: If an issue is found with the observing task after it has been transitioned to Ready, it may be transitioned back to Preparation.
+This transition could be triggered by either the Assignee, the Proposer, or the user responsible for executing the task on the Summit. 
+
+*Transition to Done*: If the task has been executed and the data collected deemed satisfactory by the Proposer and there is no need to repeat the test, 
+it can be transitioned to *Done* and removed from further planning consideration. 
+
+End states
+----------
+
+The end states are the ultimate destination of a reported ticket.
+When a ticket reaches one of these states, is will no longer be considered for scheduling.
+We start by explaining these states because they are referenced throughout the remainder of the document, specifically when describing state transitions.
+
+**Done**
+^^^^^^^^
+All work required to complete the observing block has been Done. There is no current plan to repeat the task. 
+
+**Invalid**
+^^^^^^^^^^^
+The requested observing block is no longer valid, was filed by mistake, or has been superseded by another block or other events.
+
+There are multiple ways that tickets reach these states, which are explained in the sections below.
+The Invalid state is special because it can be transitioned to from any active state in the workflow.
+
+Both Invalid and Done allow transition out of these states, which is to return to the Proposed state and start the workflow over again.
+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.
 
-    - *Transition to* ``Done``: If the task has been executed and the data collected deemed satisfactory by the ``Proposer`` and there is no need to repeat the test, 
-      it can be transitioned to ``Done`` and removed from further planning consideration. 
 
 BLOCK Ticket Management Process
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+===============================
+
 BLOCK tickets are expected to be the source of instructions for observing tasks requiring execution at the summit.