Writing Review

Review prose in markdown files (.md) and Jupyter notebook markdown cells for formatting, style, clarity, and pedagogical effectiveness.

Exclude: _external/ directory.

Part I: Formatting Standards

Terminology Conventions

• •Use "shoppers" (not "customers") when referring to end-users in e-commerce context
• •Verify consistency across all documentation

Data Columns and DataFrame Fields

Use backticks for column/field names:

Good: Each product has a unique `product_identifier`, a `category`, and a `price`.
Good: The `impressions` column tracks how many times a product was shown.
Bad:  Each product has a unique product_identifier (missing formatting)
Bad:  The **impressions** column (bold alone - use backticks instead)

Code Elements in Markdown

Functions and Methods

Use backticks with parentheses:

Good: `simulate()`
Good: `load_job_results()`
Bad:  simulate()
Bad:  simulate

Variables and Objects

Use backticks:

Good: The `job_info` object contains...
Good: Pass the `results` to the next function...
Bad:  The job_info object contains...

Parameters and Arguments

Use backticks:

Good: The `effect_size` parameter controls...
Good: Set `num_products` to 100...
Bad:  The effect_size parameter controls...

File References

Config Files

Use backticks with quotes:

Good: `"config_simulation.yaml"`
Bad:  config_simulation.yaml
Bad:  "config_simulation.yaml"

Python Modules

Use backticks:

Good: `products_rule_based.py`
Good: `online_retail_simulator`
Bad:  products_rule_based.py

Directories

Use backticks with trailing slash:

Good: `output/`
Good: `src/simulate/`
Bad:  output

Configuration Sections (YAML)

Top-Level Sections

Use BOLD UPPERCASE in prose:

Good: The **PRODUCTS** section generates...
Good: The **PARAMS** subsection controls...
Bad:  The PRODUCTS section generates...
Bad:  The products section generates...

Specific Keys

Use backticks in technical context:

Good: The `effect_size` parameter controls...
Good: Set `enrichment_fraction` to 1.0...
Bad:  The effect_size parameter controls...

Simulation Phases vs YAML Sections

Conceptual Phases

Use bold lowercase:

Good: "the **products** phase"
Good: "the **product_details** phase"
Bad:  "the products phase" (not bold)
Bad:  "the PRODUCTS phase" (wrong case)

YAML Configuration Sections

Use bold uppercase:

Good: "The **PRODUCTS** section in the YAML config..."
Bad:  "The products section in the YAML..." (lowercase)

Rule: Phase names (concepts) = lowercase bold. YAML sections = uppercase bold.

Object Types and Return Values

Use backticks for types:

Good: Returns a `JobInfo` object
Good: Returns a `DataFrame`
Bad:  Returns a JobInfo object

Emphasis and Highlighting

Bold for Concepts

Use on first introduction:

Good: The **conversion funnel** tracks customer behavior. The conversion funnel includes...
Bad:  The conversion funnel tracks... (not bold on first use)

Italics for Subtle Emphasis

Use sparingly for meta-comments:

Good: Describe *what* you want in natural language
Good: The goal is not perfectly polished code—it's *rapid insight generation*

Questions as Headers

Format important questions in bold:

Good: **Does improving product content quality increase sales?**
Good: How do customers move through the purchase journey?

Numbers and Values

Inline Numbers

Plain text for readability:

Good: Simulate 100 products
Good: A 50% increase
Bad:  Simulate `100` products (over-formatted)

Parameter Values

Use code formatting:

Good: Set `effect_size: 0.5`
Good: The default `num_products: 100`
Bad:  Set effect_size: 0.5 (not formatted)

Links and References

External Links

Format package/tool names with link on first mention:

Good: The [**Online Retail Simulator**](https://github.com/eisenhauerIO/tools-catalog-generator)
Good: We use [GitHub Copilot](https://github.com/features/copilot) to generate code.

Subsequent Mentions

Use plain bold or plain text:

Good: The **Online Retail Simulator** generates...
Good: The simulator generates...
Bad:  The [Online Retail Simulator] generates... (over-linked)

Lists and Examples

Parenthetical Examples

Use em-dash for inline examples:

Good: `**category**` (such as Electronics, Clothing, or Books)
Good: Brand names get premium suffixes ("Elite", "Pro")
Bad:  **category** like Electronics, Clothing, or Books

Code Example Values

Use quotes for strings:

Good: `"2024-11-01"`
Good: `seed: 42`
Bad:  2024-11-01 (not quoted)

Headers and Structure

Header Hierarchy

# Main Title (once per notebook - the lecture title only)
## Major Section
### Subsection
#### Rare: only for deeply nested content

Important: Each lecture notebook should have exactly ONE # heading - the lecture title. All other sections should use ## or lower. This ensures proper document structure and navigation.

Section Headers Should Be Questions (When Appropriate)

Good: ## Exploring the Generated Data
Good: ### How is revenue distributed across categories?
Bad:  ### Revenue Distribution (less engaging)

No Formulaic Summary Sections

Do not add structured summary sections at the end of lectures. Avoid:

• •"Summary" with bullet points recapping the lecture
• •"Key Concepts" or "Key Takeaways" lists
• •"Practical Implications" sections
• •"Looking Ahead" or "Next Steps" sections

Lectures should end naturally with the final content. Let the material speak for itself.

Tone and Voice

Active Voice

Good: The simulator generates a product catalog
Bad:  A product catalog is generated by the simulator

Present Tense

Good: The function writes the DataFrames to disk
Bad:  The function will write the DataFrames to disk

Instructional but Not Condescending

Good: Let's start by simulating 100 products
Bad:  Now we're going to simulate some products (too casual)
Bad:  It is necessary to simulate products (too formal)

Quick Reference

Part II: Pedagogical Clarity

Content Accuracy

Technical Correctness

• • Definitions and notation are mathematically correct
• • Equations and derivations are accurate
• • Statistical concepts are properly explained
• • Data/statistics cited are accurate and sourced

Source Alignment

For Measure Impact lectures:

• • Theory matches the referenced Mixtape chapter
• • Key concepts from the chapter are covered
• • Notation follows the source material
• • No contradictions with established methodology

Structure and Flow

Logical Progression

• • Concepts build on each other in a sensible order
• • Prerequisites are introduced before they're needed
• • Transitions between sections are clear
• • The narrative has a clear beginning, middle, and end

Section Balance

• • Theory and application sections are appropriately balanced
• • No section is disproportionately long or short
• • Complex topics get adequate depth
• • Simple topics aren't over-explained

Narrative Depth

• • Concepts are explained thoroughly with multiple paragraphs, not just stated
• • Mathematical derivations show intermediate steps, not just final results
• • The "why" is explained, not just the "what"
• • Tables organize definitions, parameters, and comparisons
• • Formal definitions use precise LaTeX notation
• • Complex ideas are decomposed into named components

Examples and Applications

Worked Examples

• • At least one complete worked example with code
• • Example is realistic and relatable
• • Steps are explained, not just shown
• • Results are interpreted, not just displayed

Business Context (for applied lectures)

• • Business question is clearly stated
• • Data generation connects to the business scenario
• • Results answer the business question
• • Limitations and caveats are discussed

Engagement and Clarity

Accessibility

• • Technical jargon is explained on first use
• • Assumes appropriate (not excessive) prior knowledge
• • Difficult concepts have intuitive explanations
• • Analogies or visual aids are used where helpful

Active Learning

• • Headers pose questions where appropriate
• • Students can run code and see results
• • Opportunities for exploration or modification exist

Completeness

No Missing Pieces

• • All referenced concepts are defined
• • No "TODO" or placeholder content in final version
• • All code cells are complete and runnable
• • Figures and tables are labeled and explained

Appropriate Scope

• • Covers the topic adequately for the course level
• • Doesn't try to cover too much in one lecture
• • Points to additional resources for deeper exploration

Part III: Checklists

Formatting Checklist

• • All column names use `column_name` format
• • All functions use `function_name()` format
• • All file references use `"filename.ext"` format
• • Phase names are lowercase bold (products)
• • YAML sections are uppercase bold (PRODUCTS)
• • Object types use backticks (`DataFrame`, `JobInfo`)
• • First introduction of concepts uses bold
• • Links use meaningful text, not "click here"
• • Headers are questions when exploring data
• • Active voice, present tense throughout
• • Uses "shoppers" not "customers" for e-commerce end-users
• • Additional resources section uses correct format: ## Additional resources header, bullet points with Author (Year). Title. Journal, volume(issue), pages.

Pedagogy Checklist

• • Concepts build logically
• • Technical jargon is explained
• • Examples are realistic and explained
• • Results are interpreted, not just shown
• • No placeholder or TODO content

Review Questions

When reviewing, ask yourself:

1. •

   Would a student understand this? Not just follow along, but actually grasp the concept.

2. •

   Is the "why" explained? Not just what the method does, but why it works and when to use it.

3. •

   Are assumptions made explicit? Students should know what conditions must hold.

4. •

   Is the business relevance clear? For applied lectures, the connection to decisions should be obvious.

5. •

   What would confuse someone? Identify potential stumbling blocks before students hit them.

Verification

After making changes, always run:

git status
hatch run ruff format .
hatch run ruff check .
hatch run build

This checks for untracked files, formats code, checks for linting issues, builds the documentation and executes all notebooks, confirming that changes don't break anything.

Success criteria:

• • All new files are under version control (git status shows no untracked files that should be committed)
• • hatch run ruff format . completes without changes
• • hatch run ruff check . passes with no errors
• • hatch run build completes successfully

Output Format

For each issue found:

1. •Location: File and line/section reference
2. •Issue: What's wrong
3. •Suggestion: How to fix it