23 update the polaris guide for the beta version

docs/Observer/Creating Proposals/adding-targets.md

@@ -1,46 +1,83 @@
+---
+title: Adding Targets
+date: 2025-10-21
+description: >
+   _Guide to adding **Targets** to your proposal_
+categories: [Examples]
+tags: [test, sample, docs]
+---
 
-# Add a Target
+Last updated: 2025-10-21 Polaris _beta_ version
+
+# Adding a Targets
 
 A fresh proposal will have no **Targets** added, and you will be presented with the following page:
 
-![add a target](targets_none.png)
+![add a target](polaris-targets-none.png)
+
+# Add a Single Target
 
+To add a single **Target** click the _Add One Target +_ button, which will bring up the _New Target_ form.
 
-To add a **Target** click the _Add +_ button, which will bring up the _New Target_ form.
+!["new target form](polaris-simbad-search-target.png)
 
-!["new target form](targets_new.png)
+In the screenshot you will see we have found the _Crab Nebula_ using the **SIMBAD search** function.
+This fills in the corresponding positional and coordinate system data for the named target, and displays 
+the target in the [Aladin Lite Sky Atlas](https://aladin.cds.unistra.fr/).
 
-In the screenshot you will see we have added the [Aladin Lite Sky Atlas](https://aladin.cds.unistra.fr/),
-and we have found the _Crab Nebula_ using the **Lookup** function. This fills in the corresponding 
-positional and coordinate system data for the named target, and displays the target in the Sky Atlas. 
 Notice that the backend uses [Simbad](https://simbad.cds.unistra.fr/simbad/) to search for the named target, such that the name must 
 exist in their databases to be successful; an appropriate error notification is displayed if the 
-named target cannot be found. 
+named target cannot be found. We have provided useful help, hints, and tips to aid in using the search
+facility. Notice that the name displayed after selecting a search item is the _main-id_ found in the Simbad 
+database. In the screenshot shown the _main-id_ for the Crab Nebula is "M 1".
 
-You may also simply click anywhere on the Sky Atlas and the corresponding positional details will be 
-updated in the RA and DEC fields (notice that these are currently displayed as degrees only, we have 
-development plans to add _HH:MM:SS_ format and to allow you to select between the units with which you 
-are most comfortable). 
+You may also double-click anywhere on the displayed Sky Atlas. This will centre the Atlas under the
+position you just double-clicked and fill out the form with a "random" target name and the corresponding 
+positional details will be updated in the RA and DEC fields. These will be displayed as sexagesimal with
+the equivalent degree value displayed under the field box. 
 
 You can also manually fill in the fields, the Sky Atlas will automatically change the view to those 
-coordinates. Notice that in this alpha version of Polaris, you can have any coordinate system you like, 
-so long as it's _J2000_. 
+coordinates. Notice that in this beta version of Polaris, you can have any coordinate system you like, 
+so long as it's _J2000_ with an ICRS reference system.
+
+You can change the name of the target after you have looked it up and before you save it as a 
+**Target**. Be aware that each target must have a unique name within a proposal. To save, click the _Save_ 
+button. This will return you to the **Targets** page of your proposal 
+now displaying the **Target** you just saved, and any other targets you may have added. Clicking _Cancel_
+on the new target form will take you back to the targets list page without saving.
+
+![list of targets](polaris-target-list.png)
+
+You may _Delete_ this **Target** if you so wish, just remember that you need at least one target in order
+to build an **Observation** for your proposal. For information, you will not be able to delete **Targets** 
+that currently belong to an **Observation** - the corresponding **Observation** must be deleted first.
 
-You may also change the name of the target after you have looked it up and before you save it as a 
-**Target**. To save, click the _Save_ button. This will return you to the _Targets_ tab of your proposal 
-now displaying the **Target** you just saved, and any other targets you may have added.
+## Adding Several Targets via File Upload
 
-![list of targets](targets_some.png)
+Instead of adding **Targets** one at a time, we have provided a means to add several **Targets** at once
+via a file upload; click the _Upload List of Targets_ button. Compatible files are **VOTable xml** (obtained 
+from _Simbad_ or another service), **Astropy generated ecsv**, or manually created txt. We recommend using 
+either the VOTable xml or the Astropy generated ecsv but if you are a masochist read on.
 
+The manually created txt file should have the following format:
 
-Please notice that the _Reference System_ should read _ICRS_ but due to some bug that has yet to be 
-squished it reads _unknown_; did I mention this was the alpha version?
+```
+#name,ra,dec,pmra,pmdec,plx,rv
+alpha,12.987,34,42,69,,99
+beta,56,78,11,13,33,112
+gamma,90,-12,38,-34,-1,-86
+```
 
-You may _Delete_ this target if you so wish, just remember that you need at least one target in order
-to build an **Observation** for your proposal.
+where you are required to provide the columns 'name', 'ra', and 'dec' of the targets, the other
+columns may be omitted with the caveat that if you provide one proper-motion ('pm') column, you must provide the
+other. The names can only be ASCII characters and the other values are integer or decimal digits. All units are in degrees 
+or degrees per second for rates. The order of the columns is not important (to the code at least, 
+to your sanity maybe). Any optional data value i.e., 'pmra', 'pmdec', 'plx', 'rv', that isn't available but for which
+you have a column should be left blank e.g., the target 'alpha' in the (made-up) list above has no parallax data. Again
+we recommend using either one of the other two formats to add a list of targets.
 
 ## Next Step
 
 If you haven't already added a **Technical Goal** then please follow the guide [here](adding-technical-goals.md).
 If you have now added at least one **Target** and one **Technical Goal** to your proposal then please 
-follow the link to [**Building Observations**](build-observation.md).
+follow the link to [**Building an Observation**](build-observation.md).

docs/Observer/Creating Proposals/adding-technical-goals.md

@@ -1,44 +1,49 @@
 ---
 title: Adding Technical Goals
-date: 2024-03-04
+date: 2025-10-21
 description: >
    _Guide to adding **Technical Goals** to your proposal_
 categories: [Examples]
 tags: [test, sample, docs]
 ---
 
+Last updated: 2025-10-21 Polaris _beta_ version
+
 # Add a Technical Goal
 
 A fresh proposal will have no **Technical Goals** and you will be presented with the following page:
 
-![no technical goals summary page](technical_goals_none.png)
+![no technical goals summary page](polaris-tech-goals-none.png)
 
 
 To add a **Technical Goal** click the _Add +_ button, which will bring up the _New Technical Goal_ form.
 
-![new technical goals form](technical_goals_new.png)
+![new technical goals form](polaris-tech-goals-new.png)
 
 
-In the screenshot you can see we have filled out the _Performance Parameters_ with some values and their 
-corresponding units; the values in the screenshot are contrived for this guide. The units are selected via a 
-drop-down menu. These values are what you would like the observation to achieve, and are not necessarily strict 
-requirements. Further explanation of each field can be found [here](???) (to-do). The _Performance Parameters_ 
-are the minimum amount of information required to _Save_ (screenshot reads _Submit_ because alpha version) a 
-**Technical Goal**. For now, we ignore the _Spectral Window_ aspect of a **Technical Goal**, to be revisited later.
+The values can be freely entered but the units are selected via a drop-down menu. These values are what you would 
+like the observation to achieve, and are not necessarily strict requirements. The _Performance Parameters_ are the 
+minimum amount of information required to _Save_ a **Technical Goal**. For now, we ignore the _Spectral Window_ 
+aspect of a **Technical Goal**, to be revisited later.
 
 After clicking _Save_ you will be brought back to the technical goals summary page, which should now display your
 newly added **Technical Goal**. 
 
 
-![technical goals summary page](technical_goals_some.png)
+![technical goals summary page](polaris-tech-goals-list.png)
+
+In the screenshot you can see we have filled out the _Performance Parameters_ with some values and their
+corresponding units; the values in the screenshot are contrived for this guide.
 
 
 Unlike **Targets**, you can also _Edit_ and _Copy_ **Technical Goals** as well as _Delete_ them. This allows you 
 to change the attributes of an existing **Technical Goal**, or quickly add other **Technical Goals** that may have 
-similar _Performance Parameters_ and/or _Spectral Windows_ without having to re-input all the data. 
+similar _Performance Parameters_ and/or _Spectral Windows_ without having to re-input all the data. If a 
+**Technical Goal** currently belongs to an **Observation** then it cannot be deleted, unless the corresponding
+**Observation** is deleted first. However, the _Edit_ and _Copy_ functions are still available.
 
 ## Next Step
 
 If you haven't already added a **Target** then please follow the guide [here](adding-targets.md).
 If you have now added at least one **Target** and one **Technical Goal** to your proposal then please follow the
-link to [**Building Observations**](build-observation.md).
+link to [**Building an Observation**](build-observation.md).

docs/Observer/Creating Proposals/build-observation.md

@@ -1,34 +1,42 @@
-
+---
+title: Build an Observation
+date: 2025-10-21
+description: >
+   _Guide to building an **Observation** for your proposal_
+categories: [Examples]
+tags: [test, sample, docs]
+---
 # Build an Observation
 
 After adding at least one **Target** and at least one **Technical Goal** you will see the following summary page 
 for **Observations**, which will be empty.
 
-![empty Observations summary page](observations_none.png)
+![empty Observations summary page](polaris-observation-none.png)
 
 
 
 To build an **Observation** click the _Add +_ button, which will bring up the new observation form.
 
-![new Observation form](observations_new.png)
+![new Observation form](polaris-observation-create.png)
 
 
-In this screenshot we have already selected our **Target**, the "crab", and our **Technical Goal**, and have
-selected the _Observation Type_ as _Calibration_ and the _Calibration intended use_ as _Pointing_. Notice that
-the _Observation Type_ is a choice between _Target_ and _Calibration_, and if you select _Target_ there is no
-"intended use" field; the **Target** is the intention of the **Observation**. For a _Calibration_ **Observation**
-there are several "intended use" options to pick from; see the [documentation](???) (to-do) for details. 
+In this screenshot we have yet to fill in the data. You must select the _Type_ of **Observation** either _Target_
+or _Calibration_. If selecting _Calibration_ you must also select the _Intended Use_ of the calibration. There 
+are several options here including _Pointing_, _Bandpass_, _Focus_, and _Delay_ amongst others.
+The messages in red describe the necessary fields that are required to create an **Observation** after selecting
+its type and intended use where appropriate.
 
-Selecting the **Target**, **Technical Goal**, and _Observation Type_ is the minimum amount of information to _Save_ 
-an **Observation** to the database. However, for the **Proposal** to pass the server side validation before 
-submission, all **Observations** in the **Proposal** must have at least one **Timing Window**. 
+Each **Observation** must have at least one **Target** and multiple selections are allowed. **Observations** can
+only have one **Technical Goal** selected, and you must provide at least one **Timing Window**. 
 
 A **Timing Window** is a timing constraint on the **Observation**, and consists of _start_ and _end_ times that 
 can be specified up to the minutes unit, an _avoid_ toggle switch that changes the meaning of the window, to be
 explained presently, and an optional note to provide additional information if required. Typically, a 
 **Timing Window** will specify the range of times when the **Observation** should be performed i.e., the _avoid_ 
 toggle is unset. However, with the _avoid_ toggle set the window then specifies the range of times when the 
-**Observation** should **_not_** be performed. 
+**Observation** should **_not_** be performed. (Notice that
+the **Timing Window** must relate to the **Proposal Cycle** _session_ interval to which you will be submitting
+the proposal - this validation check is done during the submission process.)
 
 You can add as many **Timing Windows** to an **Observation** as required by your needs. Please note that the 
 _start_ time must be at an earlier time than the _end_ time, but that different **Timing Windows** may overlap. 
@@ -38,22 +46,22 @@ Notice that we assume all times are entered as UTC.
 With all that information entered, click _Save_ to save the **Observation** to your **Proposal**. This will 
 bring you back to the _Observations_ summary page, that will now contain your newly built **Observation**.
 
-![Observations summary page](observations_some.png)
+![Observations summary page](polaris-observation-list.png)
 
 
 As with **Technical Goals** you may _Edit_ and _Copy_ **Observations** to avoid having to repeat data entry for
 **Observations** that have similar attributes. For example, using the same **Target** but for different types,
 _Target_ or _Calibration_, of **Observation** with perhaps the same **Technical Goal** and/or timing constraints.
 
-With an **Observation** now built both the **Target** and the **Technical Goal** to which is refers have their 
-_Delete_ button disabled. This prevents you from deleting either of these things while they are actively pointed 
+With an **Observation** now built both the **Target** and the **Technical Goal** to which it refers have their 
+_Delete_ button disabled. This prevents you from deleting either of these things while they are actively referred
 to by an **Observation**. In order to re-enable the _Delete_ button on **Targets** and **Technical Goals** you 
-must first delete all **Observations** that refer to them. 
+must first delete all **Observations** that refer to them.
+
+## Next Steps
 
-In this alpha version of Polaris, once you have an **Observation** with at least one **Timing Window** in your 
-**Proposal** it will pass server side validation checks, and you may submit it for review. In subsequent versions,
-you will also have to provide both **Scientific** and **Technical Justifications** to pass validation checks, and
-it is likely more things will be added to the validation check in the future.
+If you have yet to fill out the Justifications for your proposal please follow the guide at
+[**Justifications**](../Justifications/index.md)
 
 To see how to submit your proposal for review please follow the guide at 
 [**Submitting Proposals**](../Submitting%20Proposals/index.md)