Misc fixes/improvements to documentation

README.md

@@ -6,20 +6,28 @@
   trigger turn-on curves, and scalings for the assessment of the physics performance of the CMS Phase-2 L1 Menu.
 
   For further instructions on how to run the tools, see the `docs`.
+  Some documentation can also be found in the [wiki](https://github.com/cms-l1-dpg/Phase2-L1MenuTools/wiki).
 
 ## Setup
 
+  These tools are expected to be used primarily on lxplus.
+  To clone the repository run
+
+  ```bash
+  git clone [email protected]:cms-l1-dpg/Phase2-L1MenuTools.git
+  ```
+
   A standard venv with Python3.11 can be created on lxplus
   via `python3.11 -m venv <name_of_venv>` and all necessary
-  dependencies installed via `pip install .`:
+  dependencies installed via `pip install -e .`:
 
   ```bash
-  python3.11 -m venv pyenv
+  python3.11 -m venv <name_of_venv>
   source <name_of_venv>/bin/activate
-  pip install .
+  pip install -e .
   ```
 
-  **ATTENTION:** Whenever you pull changes you need to `pip install . --upgrade`
+  **ATTENTION:** If you do not use the `-e` flag (editable), you will `pip install . --upgrade` whenever you pull changes.
 
   You can then execute the tools via
 

docs/development.md

@@ -4,10 +4,10 @@
 Poetry is used as a backend for packaging and for dependency
 management. To set up a working development environment, create
 a virtual environment and install the `poetry` python package.
-Then install all develpoment dependencies:
+Then `poetry install` installs all develpoment dependencies:
 
 ```bash
-python@3.11 -m venv <name_of_venv>
+python3.11 -m venv <name_of_venv>
 source <name_of_venv>/bin/activate
 pip install poetry
 poetry install
@@ -24,7 +24,7 @@ pytest -vv
 ```
 
 to run all tests. The `-vv` option is optional and can be omitted.
-For some of the tests the presence of the V29 caching files is required.
+For some of the tests the presence of the `V29` caching files is required.
 
 
 ## Code Formatting and Linting

docs/object-performance.md

@@ -2,13 +2,16 @@
 
   The object performance tools allow the user to produce
   matching efficiency, turn-on curves, and scaling plots for
-  the various L1 objects under test.
+  the various L1 objects.
   The definition of each object to be tested is detailed in
   this [TWiki page](https://twiki.cern.ch/twiki/bin/view/CMS/PhaseIIL1TriggerMenuTools).
 
-  A detailed description of each step, together with instructions on how to set up the configuration files for the cache and plotting steps, is given in [the Wiki pages](https://github.com/cms-l1-dpg/Phase2-L1MenuTools/wiki).
+  A detailed description of each step, together with instructions on how to set up the
+  configuration files for the cache and plotting steps, is given in
+  [the Wiki pages](https://github.com/cms-l1-dpg/Phase2-L1MenuTools/wiki).
 
-  The following presents the commands to be run to produce the standard set of validation plots (cf. [these slides](https://twiki.cern.ch/twiki/pub/CMS/PhaseIIL1TriggerMenuTools/Phase2Menu_validation123x-3.pdf)).
+  The following presents the commands to be run to produce the standard set of validation
+  plots (cf. [these slides](https://twiki.cern.ch/twiki/pub/CMS/PhaseIIL1TriggerMenuTools/Phase2Menu_validation123x-3.pdf)).
 
 ## Table of content
 
@@ -17,6 +20,10 @@
   * [Reference config files](#reference-config-files)
 
 ## Caching the NTuple trees
+
+  **Note:** When running on lxplus, usually the cache files will already
+  be present in the symliked directory included with the repo.
+
   In order to run the next steps, the object
   `TTrees` from the L1NTuples need to be cached
   as `awkward` arrays saved into `.parquet` files.
@@ -27,9 +34,11 @@
   ```
 
   An example for a caching config can be found at `configs/V29/caching.yaml`.
-  The output of this step is saved to `cache`. The repository by default includes a symlink to a directory which should already contain most of the desireable object caches.
-  This step needs to be run only once per configuration (unless changes in the input L1 ntuples occur) and the `.parquet` files generated by the code can be used for all the subsequent steps of the workflow,
-  without having to open the `.root` files and load the objects every time the framework is run.
+  The output of this step is saved to `cache`.
+  This step needs to be run only once per configuration (unless changes in the input
+  L1 ntuples occur) and the `.parquet` files generated by the code can be
+  used for all the subsequent steps of the workflow, without having to open the
+  `.root` files and load the objects every time the framework is run.
 
 ## Efficiency and Scalings
   To produce matching efficiencies, turn-on curves, and L1 scalings run
@@ -47,9 +56,13 @@
   Default configuration files are contained in `configs` and should be used as
   templates for custom configurations.
 
-  The points used for the calculation of the scalings correspond to the list of threshold cuts defined in [`scaling_thresholds`](https://github.com/cms-l1-dpg/Phase2-L1MenuTools/blob/main/configs/scaling_thresholds.yaml).
+  The points used for the calculation of the scalings correspond to the list of
+  threshold cuts defined in
+  [`scaling_thresholds`](https://github.com/cms-l1-dpg/Phase2-L1MenuTools/blob/main/configs/scaling_thresholds.yaml).
 
-  The outputs will be written to the `outputs/<VERSION>` directory, where `<VERSION>` is the version of the ntuples used for the plots as specified in the `.yaml` config file (more details on the config file are given below).
+  The outputs will be written to the `outputs/<VERSION>` directory,
+  where `<VERSION>` is the version of the ntuples used for the plots as specified
+  in the `.yaml` config file (more details on the config file are given below).
   In the current version of the code, the plots will be saved in three folders under `outputs/<VERSION>`:
 
   * `distributions`: plots of the distributions (histograms) used to compute the efficiencies. For each efficiency curve plotted, these plots depict the distributions used for as numberator and denumerator in the computation of the efficiencies.

docs/objects.md

@@ -7,7 +7,7 @@ centrally, by default at
 configs/<VERSION>/objects
 ```
 
-All objects found in yaml files in this directory will be found by
+All objects defined in yaml files in this directory will be found by
 the code.
 
 ## Object configuration