Merge pull request #10 from orppst/get-started-create-new-proposal-steps

Add screenshots, update creating-proposal.md

content/en/_index.md

@@ -19,7 +19,7 @@ Polaris provides a web UI for both submitting and managing astronomical observin
 multiple telescopes.
 
 
-In addition it provides components that enable the export of proposals and  to allow their manipulation off-line
+In addition, it provides components that enable the export of proposals and  to allow their manipulation off-line
 {{% /blocks/lead %}}
 
 

content/en/docs/Getting started/Creating Proposals/_index.md

@@ -0,0 +1,62 @@
+---
+title: Creating Proposals
+date: 2023-11-01
+description: >
+   _Quick start guide to creating a new **Proposal** using Polaris_
+categories: [Examples]
+tags: [test, sample, docs]
+---
+
+###### First, Login
+
+If you haven't registered with and logged-in to Polaris please do so [now](tbc).
+
+##  Click the **Create a new proposal** button
+
+<img src="/images/getting-started/proposal_create.png" style="width: max-content" alt="polaris landing page, highlighting the create a new proposal button">
+<br />
+<br />
+
+This will bring up the new **Proposal** details form. 
+
+## Fill in the proposal details form and click **Create**
+
+<img src="/images/getting-started/proposal_create_details.png" style="width: fit-content" alt="create proposal details"> 
+<br />
+<br />
+
+The basic details of an **Observing Proposal** are the title, a brief summary, and the **Kind** of your proposal 
+either _STANDARD_, _SURVEY_, or _T.O.O._ (target-of-opportunity). These attributes can be changed after you create 
+the proposal.
+
+## The Proposal Overview
+
+Now that you have a created a new proposal you can see its **Overview** by clicking the dropdown 
+menu for the relevant proposal in the navigation pane on the left, and clicking on the _Overview_ 
+tab.
+
+<img src="/images/getting-started/proposal_overview.png" style="width: fit-content" alt="the proposal overview">
+<br />
+<br />
+
+In the screenshot example we have given our proposal the title _An awesome proposal title_, filled 
+in the summary with a very brief summary (literally), and assigned it a **Kind** of _STANDARD_. Notice 
+that, as the creator of the new proposal, you will have been automatically assigned the **PI**, or 
+Principal Investigator, role for the proposal (in the example we used for the screenshots, the 
+username is also _PI_; nobody said we had to be inventive).
+
+## Next Steps: adding Targets and Technical Goals
+
+If you now try to go to the _Observations_ tab you will be presented with the following page:
+
+<img src="/images/getting-started/observations_missing_target_goal.png" style="width: fit-content" alt="trying to add observation before adding targets and technical goals">
+<br />
+<br />
+
+In the Polaris app you must first add at least one observational **Target** and at least one **Technical
+Goal** before you can generate an **Observation** for your proposal. Notice that the yellow text in the
+screenshot is a link to take you to the corresponding page in the App. 
+
+For the next steps in this guide, please follow either the **Adding Targets** link or the **Adding Technical Goals** 
+link, the order here does not matter. The **Building Observations** page assumes you have added at least one target 
+and at least one technical goal to your proposal.

content/en/docs/Getting started/Creating Proposals/adding-targets.md

@@ -0,0 +1,58 @@
+---
+title: Adding Targets
+date: 2024-03-04
+description: >
+   _Guide to adding observational **Targets** to your proposal_
+categories: [Examples]
+tags: [test, sample, docs]
+---
+
+# Add a Target
+
+A fresh proposal will have no **Targets** added, and you will be presented with the following page:
+
+<img src="/images/getting-started/targets_none.png" style="width: fit-content" alt="add a target">
+<br />
+<br />
+
+To add a **Target** click the _Add +_ button, which will bring up the _New Target_ form.
+
+<img src="/images/getting-started/targets_new.png" style="width: fit-content" alt="new target form">
+<br />
+<br />
+
+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. 
+
+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 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_. 
+
+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.
+
+<img src="/images/getting-started/targets_some.png" style="width: fit-content" alt="list of targets">
+<br />
+<br />
+
+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?
+
+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.
+
+# Next Step
+
+If you haven't already added a **Technical Goal** then please follow the guide [here](../adding-technical-goals).
+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).

content/en/docs/Getting started/Creating Proposals/adding-technical-goals.md

@@ -0,0 +1,46 @@
+---
+title: Adding Technical Goals
+date: 2024-03-04
+description: >
+   _Guide to adding **Technical Goals** to your proposal_
+categories: [Examples]
+tags: [test, sample, docs]
+---
+
+# Add a Technical Goal
+
+A fresh proposal will have no **Technical Goals** and you will be presented with the following page:
+
+<img src="/images/getting-started/technical_goals_none.png" style="width: fit-content" alt="no technical goals summary page">
+<br />
+<br />
+
+To add a **Technical Goal** click the _Add +_ button, which will bring up the _New Technical Goal_ form.
+
+<img src="/images/getting-started/technical_goals_new.png" style="width: fit-content" alt="new technical goals form">
+<br />
+<br />
+
+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.
+
+After clicking _Save_ you will be brought back to the technical goals summary page, which should now display your
+newly added **Technical Goal**. 
+
+<img src="/images/getting-started/technical_goals_some.png" style="width: fit-content" alt="technical goals summary page">
+<br />
+<br />
+
+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. 
+
+# Next Step
+
+If you haven't already added a **Target** then please follow the guide [here](../adding-targets).
+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).

content/en/docs/Getting started/Creating Proposals/build-observation.md

@@ -0,0 +1,69 @@
+---
+title: Building Observations
+date: 2024-03-04
+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.
+
+<img src="/images/getting-started/observations_none.png" style="width: fit-content" alt="empty Observations summary page">
+<br />
+<br />
+
+To build an **Observation** click the _Add +_ button, which will bring up the new observation form.
+
+<img src="/images/getting-started/observations_new.png" style="width: fit-content" alt="new Observation form">
+<br />
+<br />
+
+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. 
+
+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**. 
+
+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. 
+
+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. 
+
+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**.
+
+<img src="/images/getting-started/observations_some.png" style="width: fit-content" alt="Observations summary page">
+<br />
+<br />
+
+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 
+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. 
+
+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.
+
+To see how to submit your proposal for review please follow the guide at 
+[**Submitting Proposals**](../../submitting-proposals)

content/en/docs/Getting started/Submitting Proposals/_index.md

@@ -0,0 +1,47 @@
+---
+title: Submitting Proposals
+date: 2024-03-04
+description: >
+   _Guide to submitting your **Proposal**_
+categories: [Examples]
+tags: [test, sample, docs]
+---
+
+{{% pageinfo %}}
+Please be aware that the submission functionality of Polaris is under active development such that this page
+may very well be out-of-date. Please bear with us while we get around to updating this page. 
+
+Last updated **2024-03-06** Polaris _alpha_ version.
+{{% /pageinfo %}}
+
+
+# Submit your Proposal
+
+Once you are happy with the details of your **Proposal**, and it has passed the server side validation checks 
+you may submit it for review.
+
+<img src="/images/getting-started/proposal_submission_ready.png" style="width: fit-content" alt="proposal submission ready">
+<br />
+<br />
+
+You will have to select the **Proposal Cycle** from the drop-down menu to which you wish to submit your **Proposal**.
+Once selected the page will display the submission deadline for that cycle.
+
+Server side validation checks currently include:
+
+* the **Proposal** _Title_, _Summary_, and _Kind_ attributes are set (the App prevents you from leaving any of these blank)
+* at least one **Observation** added with at least one **Timing Window**
+  * which requires at least one **Target** and at least one **Technical Goal**
+
+As we develop the server side validation checks this list will grow. For example, we'd expect that a **Proposal** 
+must have a **Scientific Justification** and a **Technical Justification** to be valid for review. Indeed, we 
+expect this list to expand significantly as we put Polaris in to beta-testing.
+
+If a **Proposal** doesn't pass the validation checks then you will be presented with the following page for the 
+_Submit_ tab of your proposal, which lists the problems.
+
+<img src="/images/getting-started/proposal_submission_not_ready.png" style="width: fit-content" alt="proposal submission not ready">
+<br />
+<br />
+
+Here we have created another proposal but haven't added any **Targets**, **Technical Goals**, or **Observations**.

content/en/docs/Getting started/_index.md

@@ -1,35 +1,37 @@
 ---
 title: Getting Started
-description: What does your user need to know to try your project?
+description: Prerequisites, Installation, and Core Setup
 categories: [Examples, Placeholders]
 tags: [test, docs]
 weight: 2
 ---
 
-{{% pageinfo %}}
-This is a placeholder page that shows you how to use this template site.
-{{% /pageinfo %}}
+## Prerequisites
 
-Information in this section helps your user try your project themselves.
+**To be confirmed**
 
-* What do your users need to do to start using your project? This could include downloading/installation instructions, including any prerequisites or system requirements.
+## Installation
+### For users
+[Front end GUI](https://github.com/orppst/pst-gui)
 
-* Introductory “Hello World” example, if appropriate. More complex tutorials should live in the Tutorials section.
+[Front end CLI](https://github.com/orppst/pst-cli-app) - under development
 
-Consider using the headings below for your getting started page. You can delete any that are not applicable to your project.
+### For Developers 
+[Overarching project](https://github.com/orppst)
 
-## Prerequisites
+[Back end API](https://github.com/orppst/pst-api-service)
 
-Are there any system requirements for using your project? What languages are supported (if any)? Do users need to already have any software or tools installed?
+## Setup
 
-## Installation
+Go to the application URI (TBC) and register as a new user. 
+Then login with your new credentials where you will be asked to provide your organisation details by either selecting 
+from a list of existing institutions or supplying information about your organisation if not present in the list.
 
-Where can your user find your project code? How can they install it (binaries, installable package, build from source)? Are there multiple options/versions they can install and how should they choose the right one for them?
+## Get started
 
-## Setup
+Start by going to the **Creating Proposals** page. 
 
-Is there any initial setup users need to do after installation to try your project?
+_Please note that the screenshots in this guide were taken using an alpha version of Polaris so may contain 
+some stylistic and naming differences to the version you are using._
 
-## Try it out!
 
-Can your users test their installation, for example by running a command or deploying a Hello World example?