To follow this tutorial you should have familiarity with p2: the web-based tool for the preparation of Phase 2 materials.  Please refer to the main p2 webpage (and the items in the menu bar on the left of that page) for a general overview of p2 and generic instructions on the preparation of Observing Blocks (OB).  Screenshots for this tutorial were made using the demo mode of p2, but should not differ in any way from one's experience in preparing your own OBs under your run.

Introduction

A README file is an integral part of the Phase 2 package that must be submitted together with OBs and finding charts for each Service Mode observing run. The README file is prepared with the same tool (p2) that is used to prepare the OBs. 

While writing the README, please keep in mind that the observer on Paranal has to deal with many different programmes. Therefore, a README should be concise and contain only information necessary to correctly execute your service mode observations. As much as possible, the observing constraints and strategy has to be encoded in the Observing Blocks (OBs) and this information should then not be repeated in the README.

In the following, we will show how to fill-in the README form. Please notice that, as for the OBs, any time that the README is edited with new content, the latter is directly saved on the ESO database.

Editing the README

In p2, please first select a given Run for which you are preparting the Phase 2 material, by clicking on the run name on the left hand column Your Observing Run. The tab that allows you to manipulate your README file is called Readme (see figure above). 

For the purpose of this tutorial, we will prepare a realistic Readme, taking examples from different instruments.  We will go through all required steps to fill in the README form for the first run and check it in. We will then use this README file as a starting point for the other observing run, taking advantage of the import/export functionalities described in the above section.

Filling out the README form

In the main p2 window, select the appropriate run in the list of folders, for which you want to prepare a README file. 

Then please click on the Readme tab to display the different component of the README. 

Readme tab:

Below the run information are three tabs which allow you to fill the readme, specify pre-imaging sources, and go through a checklist. You select the leftmost (readme) tab to first enter the estimated total execution time of the OBs you submitted for this run. To get this information, you can simply run the Execution Time report on all the OBs of your run, and then copy and paste the computed time in this field.

In order to enter specific information related to your run, please select the vertically stacked tabs (see figure above), some of which have a red triangle reminding you that filling these is mandatory. Each gives access to a section of the README file. By clicking on a tab, the corresponding section is displayed on the right-hand side. The information entered on these tabs will be read by the night astronomer just before executing your program so that no detail is overlooked for a successful observation!

For every section, you can input free format text. For tabs with a red triangle, a text example might be displayed in light grey in the input field the first time you select this tab. When you click on it to enter your text, the light grey text disappears. Only after entering text will also the red alert triangle disappear. For tabs without red triangle (non-mandatory tabs), hovering with the mouse over the tab label will display information on this tab. In some cases, a default text has already been entered. Please keep in mind that all changes made to the file are effective immediately (i.e. there is no longer a "Cancel" button"). The list of sections is as follows (those marked with a star (*) are mandatory):

• General Description*: short summary of observing programme, providing the night astronomer with any information needed to meet your science objective (e.g. required SNR). Also, please mention here any information necessary to identify the correct target in case there could be a doubt at the telescope (e.g. in the case of close companions!). Decision paths and/or OB modification requests that depend on the outcome of previously executed OBs are not allowed. Any more detailed execution instructions should be put in the "Special Execution Requirements" tab - please do not just duplicate the information!
• Waiver Requests: short summary of any approved Phase 2 waiver requests, including when they were submitted and when they were approved. These alert the night astronomer to pay attention to non-standard procedures.
• Critical Observing Condition Constraints*: any critical information about required observing conditions, but only those which could not be entered in the OB! For example, the specification of a coherence time for VLTI observations could be useful or a minimum image quality to avoid saturation. 
• Time-Critical Aspects*: Please mention briefly time critical aspects, if any, encoded in the OBs or OB containers such as absolute time windows. Also mention aspects which cannot be encoded, such as coordinated observations between UT1 and UT2.
• Special Execution Requirements: should you have a dedicated execution procedure for your run, please use this section to describe it.
• Special Calibration Information: if you have submitted OBs for calibration, please describe them here, why you have submitted them, and how they should be executed relative to your science OBs (e.g. same night, once per observing run, etc.), unless they are submitted as part of an OB concatenation. 
• ToO Information (onlt ToO runs): please indicate that this is a Target of Opportunity programme and give any special details.
• ToO Activators List (only ToO runs): here you should list people who are allowed to trigger the observations for this ToO run.

Pre-imaging tab:

Just to the right of the readme tab is the pre-imaging tab. If your run is actually a pre-imaging run, check the box next to the question "Is this a pre-imaging run?".

If your run uses some pre-imaging data, please specify which instrument(s) were used as the pre-imaging source(s) be selecting them from the list under the "Sources" field on the right. Hold down the Ctrl key while selecting instruments with the left mouse button if more than one instrument was used for the pre-imaging. If you happen to use a source of pre-imaging which is not in the proposed list, you have the possibility to specify it in the field named "Other". Simply enter the name(s) of the instrument(s) that was (were) used. One final remark: the choice of the pre-imaging sources does not appear for the instrument VIMOS, because no other instrument than VIMOS itself can be used for pre-imaging.

Checklist tab:

Now, let's have a look at the third and last tab of the main Readme window. It contains a series of questions that you must answer. This latter part is designed as a check-list for your observing runs, for you to make sure that you did not forget any important information, and that your OBs comply with the defined, instrument-specific rules for Service Mode observations.

Please select the appropriate answer for each question. This can be either Yes or N/A (Not Applicable) if a question does not apply to your particular run. Please take the time to read carefully every question before answering, as the check-list is not the same for all instruments. Also, as said above, some questions will or will not apply to your run, depending on its intrinsic characteristics (observing mode, type of program, etc.). After having answered all of the questions, the red triangle on this tab will disappear.

Exporting and Importing the README

It is possible to export/import the README. The format of the REAMDE file is JSON. In order to export the README, please click on a given run to select it.

This page is valid for all instruments

P2 Documentation

• General documentation