orppst · pahjbo · Oct 29, 2025 · Oct 24, 2025 · Oct 28, 2025 · Oct 28, 2025
diff --git a/docs/Observer/Creating Proposals/adding-targets.md b/docs/Observer/Creating Proposals/adding-targets.md
@@ -7,7 +7,7 @@ categories: [Examples]
 tags: [test, sample, docs]
 ---
 
-Last updated: 2025-10-21 Polaris _beta_ version
+Last updated **2025-10-24** Polaris _beta_ version.
 
 # Adding a Targets
 
@@ -33,7 +33,7 @@ database. In the screenshot shown the _main-id_ for the Crab Nebula is "M 1".
 
 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
+coordinates for 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 
@@ -72,9 +72,9 @@ where you are required to provide the columns 'name', 'ra', and 'dec' of the tar
 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.
+to your sanity maybe). Any optional data value i.e., 'pmra', 'pmdec', 'plx', 'rv' (radial velocity), 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 ('plx') data.
+Again we recommend using either one of the other two formats to add a list of targets.
 
 ## Next Step
 

diff --git a/docs/Observer/Creating Proposals/adding-technical-goals.md b/docs/Observer/Creating Proposals/adding-technical-goals.md
@@ -7,7 +7,7 @@ categories: [Examples]
 tags: [test, sample, docs]
 ---
 
-Last updated: 2025-10-21 Polaris _beta_ version
+Last updated **2025-10-24** Polaris _beta_ version.
 
 # Add a Technical Goal
 
@@ -21,10 +21,14 @@ To add a **Technical Goal** click the _Add +_ button, which will bring up the _N
 ![new technical goals form](polaris-tech-goals-new.png)
 
 
-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.
+The field 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 rather than strict requirements. The _Performance Parameters_ are the 
+minimum amount of information required to _Save_ a **Technical Goal**. 
+
+**Spectral Windows** are optional but if provided consist of a _start_ and _end_ frequency defining the range
+of the EM-spectrum you are interested in, the _resolution_ of that range, a _polarization_ option, and whether the
+frequency of the range is a _sky frequency_. The _Spectral point_ of the _Performance Parameters_ should be related
+to this range. 
 
 After clicking _Save_ you will be brought back to the technical goals summary page, which should now display your
 newly added **Technical Goal**. 

diff --git a/docs/Observer/Creating Proposals/build-observation.md b/docs/Observer/Creating Proposals/build-observation.md
@@ -6,6 +6,9 @@ description: >
 categories: [Examples]
 tags: [test, sample, docs]
 ---
+
+Last updated **2025-10-24** Polaris _beta_ version.
+
 # Build an Observation
 
 After adding at least one **Target** and at least one **Technical Goal** you will see the following summary page 
@@ -27,31 +30,30 @@ The messages in red describe the necessary fields that are required to create an
 its type and intended use where appropriate.
 
 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**. 
+only have one **Technical Goal** selected. **Timing Windows** are optional, and in general refer to some
+(external) observation that relates to your proposal in some way. 
 
 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. (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. 
-In this case, it is recommended to write optional notes to provide context for anyone reviewing your proposal. 
-Notice that we assume all times are entered as UTC. 
+**Timing Window** will specify when an external observation will 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 external
+observation will **_not_** be performed. 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. It is recommended to write optional notes to provide context for anyone reviewing your 
+proposal. Notice that we assume all times are entered as UTC. Generally, most proposals will not be using this feature.
 
-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**.
+With the required information, Type, Target(s), and Technical Goals, 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](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.
+**Observations** that have similar attributes. Due to restrictions in the backend code you cannot change the _Type_
+of an existing **Observation**. If you wish to create an **Observation** with a different _Type_ you must 
+create a new **Observation** rather than copying one. 
 
 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

diff --git a/docs/Observer/Creating Proposals/polaris-home-page-light.png b/docs/Observer/Creating Proposals/polaris-home-page-light.png
diff --git a/docs/Observer/Creating Proposals/polaris-observation-create.png b/docs/Observer/Creating Proposals/polaris-observation-create.png
diff --git a/docs/Observer/Creating Proposals/polaris-observation-list.png b/docs/Observer/Creating Proposals/polaris-observation-list.png
diff --git a/docs/Observer/Investigators/index.md b/docs/Observer/Investigators/index.md
@@ -0,0 +1,40 @@
+
+## Adding Investigators
+The **Investigators** section of your proposal will list all the people currently associated with the 
+proposal either as Principal Investigators (PIs) or as Co-Investigators (CoIs). 
+
+![proposal list investigators](polaris-investigators.png)
+
+
+As a PI you may add other users of _Polaris_ as **Investigators** to the proposal. To do this click the
+_Add +_ button which will bring up the following form:
+
+![polaris add investigator](polaris-investigators-add.png)
+
+You may search for other users of _Polaris_ using their email address, but you must fully specify the
+address to find the specific person (in other words, you must know the other person's email address to
+find them - GDPR: the gift that keeps on giving). In the screenshot above you will see that we have found
+the (fake) user "Edmond Halley" as we knew the (fake) email address assigned to that user. Click _Save_
+to add that person as an **Investigator** to the proposal. Notice that you can specify the _Type_ of 
+**Investigator**, either a PI or a CO-I, and if the proposal is for a PhD project.
+
+In future versions of _Polaris_ this will also email that user about their addition to the proposal.
+
+## Swapping Roles
+
+In the screenshot below we have added "Edmond Halley" as a CoI to the proposal.
+
+![polaris list investigators PI and CoI](polaris-investigators-2.png)
+
+You will notice alongside the _Delete_ button, which will remove the person as an **Investigator** from
+the proposal, is a _Swap Role_ button which allows you to switch a person's "type" of **Investigator**;
+PI -> CoI or CoI -> PI. There is a restriction on this: a proposal _must_ have at least one PI. If as
+the only PI you want to swap roles to a CoI, you must first switch a CoI to a PI. We would recommend
+that you inform the CoI that you wish to switch to being a PI as a courtesy, but there are no 
+restrictions in Polaris to enforce this. 
+
+Currently, you cannot edit an existing **Investigator**. If, for example, you forget to check the
+"Is this for a PhD?" checkbox when adding a person as an **Investigator**, you must first _Delete_
+them from the proposal, then re-add them (remembering to check the checkbox).
+
+If you haven't already, please now follow the guide about [**Submitting your proposal**](../Submitting%20Proposals/index.md)
diff --git a/docs/Observer/Investigators/polaris-investigators-2.png b/docs/Observer/Investigators/polaris-investigators-2.png
diff --git a/docs/Observer/Investigators/polaris-investigators-add.png b/docs/Observer/Investigators/polaris-investigators-add.png
diff --git a/docs/Observer/Investigators/polaris-investigators.png b/docs/Observer/Investigators/polaris-investigators.png
diff --git a/docs/Observer/Justifications/index.md b/docs/Observer/Justifications/index.md
@@ -1,9 +1,16 @@
+
+Last updated **2025-10-24** Polaris _beta_ version.
+
 ## Filling out Justifications
 
 In Polaris there are two **Justification** "flavours": **Scientific** and **Technical**.
 
 Both **Justifications** are to be provided as LaTex text strings. That is, text decorated with
-the usual LaTex commands for figures, tables, and citations (or whatever else you wish to put in your document)
+the usual LaTex commands for figures, tables, and citations (or whatever else you want to insert into your document).
+
+In the current version of Polaris you must manually save (urgh!) your **Justification** texts. We recommend creating
+and editing the texts elsewhere then copy-paste them into Polaris. In future versions of Polaris we will make the
+Justifications a "save as you type" service. 
 
 These texts will be inserted into the following "main.tex" file under the relevant section headings:
 
@@ -53,7 +60,11 @@ These texts will be inserted into the following "main.tex" file under the releva
 ```
 The ellipsis (...) in the file replaces a lengthy section where we define custom "insert figure" functions. These
 functions are described in detail in the _Help_ tab found on the **Justifications** page in Polaris. Also see the
-**Custom Insert Figure Functions** section below.
+[**Custom Insert Figure Functions**](#custom-insert-figure-functions) section below.
+
+We are using our own bibliography style template that (generally) gives only the sufficient details of a reference
+to find the associated article. We've done this in an effort to reduce "bloat" in the _References_ section of the
+compiled document.
 
 The following screenshot shows the Justifications page in Polaris. Please notice that the two **Justification**
 text areas are found in separate tabs labelled _Scientific Justification_ and _Technical Justification_, along with 
@@ -89,8 +100,9 @@ Please note that image formats are restricted to '.jpg', '.png', '.eps', and '.p
 be aware that uploading an image file with the same filename as an existing file
 will overwrite that file, and there will be no warning. You cannot have multiple bibliography files.
 
-We are using our own bibliography style template that (generally) gives only the sufficient details of a reference
-to find the associated article. 
+Justification resource files are considered to be **Supporting Documents** and as such can also be viewed and
+downloaded in the **Documents** section of Polaris. The documents belong to a given proposal and all _Investigators_
+associated with the proposal may view and download the files any other investigator has uploaded.
 
 ## Custom Insert Figure Functions
 
@@ -110,6 +122,9 @@ and 1, defining the width of the figure in terms of the text-width. It defaults
 0.5 for the single figure cases, and is an even division of the total text-width for
 the multiple figure cases. If supplied, the width parameter for the multiple figure
 cases applies to each of the images in the figure, rather than the whole figure itself.
+The astute among you will have deduced then that the product of the width
+value with the number of figures must not exceed one, else the figures will overflow
+the text.
 
 The **filename** parameter(s) should match the name of the image file(s) that you wish to
 insert. You may exclude the dot extension part of the filename, just remember that the filename
@@ -124,16 +139,12 @@ multiple figure cases, the 'filename' should be the name of the first filename p
 edge-case issue with this labelling strategy. If you have a single figure that uses an image file repeated
 as the first image in a multiple figure command, you'll get a naming conflict. The most straightforward 
 way around this issue would be to exclude the dot extension for one of the filenames. If you're including
-the same image in more than two figures (though you'd better have a good reason for doing this) then you could upload 
+the same image in more than two figures (I mean, _WHY_!?) then you could upload 
 the image with different filenames such that the figure labels will be different.
 
 Notice that the two figure and three figure functions will place the images in a
 single row, whereas the four figure function will place the images in a two-by-two
-arrangement.The astute among you will have deduced then that the product of the width
-value with the number of figures must not exceed one, else the figures will overflow
-the text. In the case of the four-figure command due to the two-by-two arrangement,
-two times the width parameter must not exceed one. For the multiple figure functions,
-each image will be labelled '(a)' through to '(d)' where appropriate.
+arrangement. For the multiple figure functions, each image will be labelled '(a)' through '(d)' where appropriate.
 
 If the multiple figure-caption layout is not to your liking, or you have more than four images to place in a figure,
 then you can always create your own multiple figure as a single image file and use the "onefigure" command.
@@ -144,15 +155,18 @@ or 'r' or 'R' for the image on the right. The uppercase version allows the image
 float, whereas the lowercase version means exactly here. (Our command uses the
 'wrapfigure' environment from the 'wrapfig' package).
 
+Of course, you can entirely ignore these custom insert figure functions and use the standard Latex syntax for
+inserting figures (using the 'graphicx' package). 
+
 # Compiling your Justification
 
-To compile your **Justification** document simply click the _Compile to PDF_ button. We
+To compile your **Justification** document click the _Compile to PDF_ button. We
 recommend keeping 'Warnings as errors' checked. After a short delay waiting for the compilation 
 to complete on the server, a modal will open displaying the status of the compilation.
 
-If you have compilation errors they will be listed in the _Latex Status_ section of the modal.
+If you have compilation errors they will be listed in the _Compilation output_ section of the modal.
 Typically, these will be caused by typos in the LaTex commands or missing resource files. To illustrate
-in the following screenshot we have tried to compile a document with an inserted a figure using
+in the following screenshot we have tried to compile a document with an insert figure command using
 an image file named 'missing' we have yet to upload to the server.
 
 ![polaris Justification compilation failure](polaris-justifications-failure.png)
@@ -169,8 +183,12 @@ If your compilation was successful you will see the following output in the moda
 
 It will give you a page count and a _Download PDF_ button that when clicked downloads the compiled document.
 Another _Download PDF_ button will also appear in the **Justifications** main page. Please be aware that the
-button on the Justifications main page, will download the latest _successfully_ compiled document only.
+button on the Justifications main page, will download the latest _successfully_ compiled document only. That is,
+any edits to your Justification texts that do not compile successfully will not appear in the downloadable
+document obtained from the button on the main page (this may be obvious to most of you, but we know what some of you are like).
 
-For your information, you will see a _CYCLE ID HERE_ placeholder in the header of the document. This is for the
+For your information, you will see a "_CYCLE-ID-HERE_" placeholder in the header of the document. This is for the
 Time Allocation Committee (of a particular Proposal Cycle) use only, and is replaced with an actual value upon 
-submission of the proposal to a cycle.
+submission of the proposal to a cycle.
+
+If you haven't already, please now follow the guide about uploading [**Supporting Documents**](../Supporting%20Documents/index.md).