Docs: Track D outputs guide (workbook)

docs/source/workbook/index.rst

@@ -15,4 +15,5 @@ PyStatsV1 Workbook
    track_c
    track_d_student_edition
    track_d
+   track_d_outputs_guide
    track_d_lab_ta_notes

docs/source/workbook/track_d.rst

@@ -137,6 +137,9 @@ By default, Track D scripts write artifacts to:
 * ``outputs/track_d/`` — tables, memos, and small machine-readable summaries
 * ``outputs/track_d/figures/`` — charts created by chapters that plot results
 
+For a practical walkthrough of the most common output files (CSV/JSON/PNG) and how to use them in a
+write-up, see :doc:`track_d_outputs_guide`.
+
 A typical chapter produces:
 
 * one or more ``.csv`` artifacts (tables you can open in Excel)

docs/source/workbook/track_d_lab_ta_notes.rst

@@ -228,6 +228,7 @@ TA line: “Trial balance is the structured ledger; statements are the story.”
    pystatsv1 workbook run d01
 
 It prints **Checks** and **Key metrics**, then writes artifacts under ``outputs/track_d``.
+If students ask "what is this file?", point them to :doc:`track_d_outputs_guide`.
 
 7.1 Checks (what they mean)
 ---------------------------

docs/source/workbook/track_d_outputs_guide.rst

@@ -0,0 +1,221 @@
+Track D Outputs Guide
+=====================
+
+This page explains what Track D writes to disk when you run workbook scripts, where those files go, and
+how to use them in a lab, assignment, or your own analysis.
+
+Why outputs matter
+------------------
+
+Track D is designed so you practice two real-world skills at once:
+
+1. **Accounting-data discipline**: checks that the data behave like a coherent accounting system
+   (balanced postings, accounting equation consistency, etc.).
+2. **Analytics discipline**: metrics, tables, and plots that turn accounting data into decisions.
+
+The **files written to** ``outputs/`` are the evidence trail for both.
+
+Where outputs go
+----------------
+
+By default, Track D scripts write into a folder under your workbook directory:
+
+.. code-block:: text
+
+   <your_workbook_folder>/
+     outputs/
+       track_d/
+
+Example (Windows):
+
+.. code-block:: text
+
+   C:\Users\nicho\Videos\Python\Test6PyStatsV1\track_d_workbook\outputs\track_d
+
+All Track D scripts use the same convention so you always know where to look.
+
+Tip: if you run a script and nothing appears to change in ``outputs/track_d``, you may not be in the
+workbook folder. Run ``pwd`` (Git Bash) to confirm you are inside your ``track_d_workbook`` directory.
+
+What kinds of files you get
+---------------------------
+
+Track D outputs are intentionally simple and "Excel-friendly":
+
+**1) Summary JSON (machine-readable)**
+
+Many chapters write a compact ``*.json`` summary you can:
+
+* read in a text editor
+* load in Python for grading or reporting
+* compare across runs (did your results change?)
+
+**2) Tables as CSV (spreadsheet-friendly)**
+
+Common derived tables are written as ``*.csv`` so you can open them in:
+
+* Excel / Google Sheets
+* pandas
+
+These are often the best starting point for "what is the data doing?"
+
+**3) Plots as PNG (report-friendly)**
+
+Chapters that produce visuals write ``*.png`` files so you can paste them into:
+
+* a lab write-up
+* a slide deck
+* a memo
+
+**4) Human-readable Markdown summaries (quick scan)**
+
+Some utilities (like ``d00_peek_data``) write a ``*.md`` file that you can read immediately.
+
+The Track D output folder layout
+--------------------------------
+
+After you run a few scripts, ``outputs/track_d`` will look something like this:
+
+.. code-block:: text
+
+   outputs/track_d/
+     d00_peek_data_summary.md
+     business_ch01_summary.json
+     business_ch01_cash_flow_bridge.png
+     business_ch01_trial_balance.png
+     ...
+
+The exact filenames vary by chapter.
+
+**The most important rule:** each chapter script declares its expected outputs at the top of the file.
+Open the script (in your workbook folder under ``scripts/``) and look at the docstring.
+
+Example from Chapter 1:
+
+.. code-block:: text
+
+   scripts/business_ch01_accounting_measurement.py
+     Outputs -> outputs/track_d/
+       - business_ch01_summary.json
+       - business_ch01_trial_balance.png
+       - business_ch01_cash_flow_bridge.png
+
+Interpreting the console output
+-------------------------------
+
+Most Track D scripts print two blocks to your terminal:
+
+**Checks**
+  These are pass/fail guards. They answer: *"Is the dataset coherent?"* and *"Did we violate an
+  accounting invariant?"*
+
+**Key metrics**
+  These are the results. They answer: *"What happened in the business?"* and *"What should we do next?"*
+
+Example (abridged):
+
+.. code-block:: console
+
+   $ pystatsv1 workbook run d01
+
+   Checks:
+   - transactions_balanced: True
+   - accounting_equation_balances: True
+
+   Key metrics:
+   - sales_total: 4079.3879
+   - gross_margin_pct: 0.4500
+   - net_income: -2155.5873
+   - ending_cash: 2974.2179
+
+How to explain that to students:
+
+* **Checks** tell you whether it's safe to trust the results.
+* **Metrics** are the business story.
+
+For example, a negative net income does *not* mean the analysis "failed". It might mean:
+
+* the business spent heavily in a startup month (rent, equipment, payroll),
+* revenue hasn't ramped up yet,
+* or costs were higher than expected.
+
+The job of the analyst is to connect those numbers back to the underlying transaction patterns.
+
+Fast workflow: from outputs to a write-up
+-----------------------------------------
+
+This is a reliable "lab rhythm" that works for almost any Track D chapter:
+
+1. Run the script.
+
+   .. code-block:: console
+
+      pystatsv1 workbook run d01
+
+2. Read the console output (Checks + Key metrics).
+
+3. Open the files in ``outputs/track_d``.
+
+   * open ``*.png`` plots first to get intuition
+   * open ``*.csv`` tables next to find the rows driving the story
+   * use the ``*.json`` summary as your "official" numbers
+
+4. Write 4-6 sentences:
+
+   * What checks matter here and did we pass them?
+   * What are the two most important metrics?
+   * What is your hypothesis for why those numbers look that way?
+   * What would you check next (a drill-down or follow-up plot)?
+
+Optional: changing the output location
+--------------------------------------
+
+Most Track D scripts support an ``--outdir`` argument.
+
+This is useful if you want one folder per lab group, or you want to keep a "clean" outputs folder.
+
+.. code-block:: console
+
+   pystatsv1 workbook run d01 --outdir outputs/track_d_groupA
+
+If you are new to command-line tools, ignore this at first and use the default.
+
+Common gotchas
+--------------
+
+**"My outputs aren't showing up"**
+  Make sure you are in the workbook folder (the one that contains ``data/``, ``scripts/``, and
+  ``outputs/``). In Git Bash: ``pwd``.
+
+**"I edited the data and now results look weird"**
+  Track D ships canonical seed=123 datasets so everyone starts from the same baseline.
+  If you want to reset, run:
+
+  .. code-block:: console
+
+     pystatsv1 workbook run d00_setup_data --force
+
+**"Why are there so many files?"**
+  This is intentional. In real analytics work, outputs are what let you:
+
+  * reproduce results
+  * audit calculations
+  * review someone else's analysis
+  * grade consistently
+
+Appendix: reading a JSON summary in Python
+------------------------------------------
+
+If you want to pull "official" metrics into a notebook, start with the JSON summary.
+
+.. code-block:: python
+
+   import json
+   from pathlib import Path
+
+   summary_path = Path("outputs/track_d/business_ch01_summary.json")
+   summary = json.loads(summary_path.read_text(encoding="utf-8"))
+
+   summary["key_metrics"]["net_income"], summary["key_metrics"]["gross_margin_pct"]
+
+You can then build your own tables/plots on top of those saved artifacts.

docs/source/workbook/track_d_student_edition.rst

@@ -129,6 +129,7 @@ A good weekly rhythm:
 
 1) Run the chapter script (``pystatsv1 workbook run dXX``).
 2) Open what it writes in ``outputs/track_d/`` (tables + summaries).
+   If you are not sure what a file is for, use :doc:`track_d_outputs_guide`.
 3) Answer the chapter questions *in words* (what changed, why, what action follows).
 4) Run the smoke checks (``pystatsv1 workbook check business_smoke``).