doc: clarify step 1 chef and dev usage (#321)

Author: c-dilks

doc/chef_guide.md

@@ -5,7 +5,14 @@ Please report _any_ issues to the software maintainers, such as warnings or erro
 
 ## :green_circle: Step 1: Fill Timeline Histograms
 
-Use the "qtl" model as part of your usual cooking workflow; see [the Chefs' documentation wiki](https://clasweb.jlab.org/wiki/index.php/CLAS12_Chef_Documentation). Output files will appear in your chosen output directory, within `hist/detectors/`.
+This step is integrated in the cooking workflow using the "qtl" model; see [the Chefs' documentation wiki for details](https://clasweb.jlab.org/wiki/index.php/CLAS12_Chef_Documentation). Output files will appear in your chosen output directory, within `hist/detectors/`.
+
+<details>
+<summary>If you are not using the cooking workflow...</summary>
+
+> See [the detailed procedure's Step 1](/doc/procedure.md) instead. The cooking workflow's "qtl" model just runs `qtl histogram` with the appropriate arguments.
+
+</details>
 
 <details>
 <summary>For physics QA timelines...</summary>
@@ -44,5 +51,5 @@ A URL will be printed upon success, and a link will appear in [`clas12mon`](http
 
 ---
 
-For more details, such as producing physics QA timelines, see other guides in
+For more details, see other guides in
 [the table of contents](/README.md) or reach out to the software maintainers.

doc/dev_notes.md

@@ -119,12 +119,12 @@ outfiles
 
 # Notes on SWIF Workflows
 
-For [CLAS12 `swif` workflow](https://github.com/baltzell/clas12-workflow) integration, the `bin/qtl histogram` command (which normally generates `slurm` jobs) has a specific mode `--swifjob`:
+For chef cooking workflow integration, the `bin/qtl histogram` command (which normally generates `slurm` jobs) has a specific mode `--swifjob`:
 ```bash
 qtl histogram --swifjob --focus-detectors   # generate files for detector timelines
 qtl histogram --swifjob --focus-physics     # generate files for physics QA timelines
 ```
-Either or both of these commands is _all_ that needs to be executed on a runner node, within [`clas12-workflow`](https://github.com/baltzell/clas12-workflow); calling one of these will automatically run the wrapped code, with the following assumptions and conventions:
+Either or both of these commands is _all_ that needs to be executed on a runner node, within the cooking workflow; calling one of these will automatically run the wrapped code, with the following assumptions and conventions:
 - input HIPO files are at `./` and only a single run will be processed
 - run number is obtained by `RUN::config` from one of the HIPO files; all HIPO files are assumed to belong to the same run
 - all output files will be in `./outfiles` (no `$dataset` subdirectory as above)

doc/procedure.md

@@ -1,5 +1,8 @@
 # Procedure for Timeline Production
 
+> [!NOTE]
+> Chefs should follow the [chef's guide](/doc/chef_guide.md), since some of the timeline procedure is integrated in the chef cooking workflow.
+
 The main script for running timelines is `qtl`:
 ```bash
 qtl --help
@@ -17,19 +20,19 @@ Both of these timeline types are produced in the following steps (🟢) .
 
 ## 🟢 Step 1: Histogramming
 
-This step reads input HIPO files (_e.g._, DST or `mon` files) and produces histograms and auxiliary files, which are then consumed by Step 2 to produce the timelines. Since many input files are read, it is recommended to use a computing cluster.
-
-This step can either be run during the usual data cooking procedure, using [`clas12-workflow`](https://github.com/baltzell/clas12-workflow) (see its usage guide), or it may be run separately on already-cooked data using:
+This step reads input HIPO files (_e.g._, DST or `mon` files) and produces histograms and auxiliary files, which are then consumed by Step 2 to produce the timelines. Run:
 ```bash
 qtl histogram
 ```
 Running it with no arguments will print the usage guide; use the `--help` option for more detailed guidance.
 
+> [!NOTE]
+> This step is integrated in the chef's cooking workflow; see the [chef's guide](/doc/chef_guide.md) for more information.
+
 > [!NOTE]
 > If you are performing physics QA for QADB, consider using [**prescaled trains**](/qa-physics/prescaler) (and `qtl histogram` will need the `--flatdir` argument)
 
 ### Example
-If using `clas12-workflow`, see it's documentation; otherwise if using `qtl histogram`:
 ```bash
 qtl histogram -d rga_sp19_v5 /volatile/clas12/rg-a/production/pass0/sp19/v5/mon
 ```
@@ -64,11 +67,11 @@ qtl physics   # for physics timelines (will eventually be combined with 'qtl ana
 > - use the scripts' `-o` option to set the output locations
 
 ### Example
-**If** you used `clas12-workflow` for Step 1, the script arguments should be
+**If** you used the chef's cooking workflow for Step 1, the script arguments should be
 ```bash
 qtl analysis -i /path/to/output/files -p some/publish/directory/rga_sp19_v5
 ```
-- the output from `clas12-workflow` is `/path/to/output/files`; its subdirectories should be run numbers
+- the output from the cooking workflow is `/path/to/output/files`; its subdirectories should be run numbers
 - the publishing directory given by `-p` is a subdirectory of the web server; see `qtl analysis` usage guide
 
 **Otherwise**, you may omit the `-i /path/to/output/files` option (unless you customized it from Step 1)