week-5-module-2

Running

week-5-module-2 / docs /04_developer_log.md

Upload 4 files

46302e8 verified 9 months ago

6.47 kB

Developer Log & Changelog

This document tracks the evolution of the "Introduction to Statistical Methods" interactive lesson.

Feature: Removed the KaTeX dependency entirely. All mathematical notation is now rendered using standard Unicode characters.
Rationale: This change was prompted by a module resolution error related to aliased paths (@/). Instead of a small patch, a larger architectural simplification was chosen to improve long-term maintainability. This eliminates an external dependency, simplifies the rendering logic, and makes the codebase lighter.
Implementation:
- Deleted the KatexRenderer.tsx and TextWithMath.tsx components.
- Refactored ContentRenderer.tsx, ContentPage.tsx, and Quiz.tsx to render strings directly, using dangerouslySetInnerHTML to preserve HTML formatting like <strong>.
- Converted all TeX strings in slides.ts to their Unicode equivalents (e.g., $$\\hat{p}_1$$ is now p̂₁).
- Removed unused KaTeX styles from appStyles.ts.
Documentation: Updated the architecture and rendering protocol documents to reflect the new Unicode-based approach.

Feature: A major architectural refactor focused on code quality, maintainability, and simplification.
Rationale: To align the codebase with modern frontend best practices, making it more robust, scalable, and elegant. The goal was to clean the codebase, remove unused elements, and simplify data structures without altering pedagogical content.
Implementation:
- Unified Data Structure: Refactored the SlideData interface in slides.ts to use a single, unified content array. Disparate fields like paragraphs, listItems, and formulas were replaced by an array of typed ContentItem objects (e.g., {type: 'paragraph', text: '...'}).
- Centralized Rendering Logic: Created a new ContentRenderer.tsx component. This component is now responsible for dynamically rendering the content array, centralizing the display logic for paragraphs, lists, and formulas.
- Component Simplification: Simplified the ContentPage.tsx component, turning it into a pure layout component that delegates all content rendering to the new ContentRenderer.
- Code Cleanup: Removed the unused calculatorLabels property from the SlideData interface and streamlined the rendering path in SlideRenderer.tsx.
Documentation: Updated docs/02_architecture.md and docs/03_rendering_protocol.md to reflect the new, cleaner architecture.

Feature: Migrated all mathematical notation rendering from simple Unicode to the powerful KaTeX library.
Rationale: To provide professional, accessible, and high-quality mathematical typesetting, significantly improving the application's visual polish and academic credibility.
Implementation:
- Added KaTeX library via CDN.
- Created a new KatexRenderer.tsx component to safely render TeX strings.
- Created a new TextWithMath.tsx component to parse inline math (using a $$...$$ delimiter) within paragraphs.
- Converted all math content in slides.ts to TeX syntax.
- Updated all relevant components to use the new rendering system.
Documentation: Overhauled docs/03_rendering_protocol.md to reflect the new KaTeX standard.

Feature: Added a comprehensive docs/ folder to house all project documentation.
Content: Created new markdown files detailing the project's pedagogical framework (01_pedagogy.md), technical architecture (02_architecture.md), and a developer log (04_developer_log.md).
Refactor: Migrated the mathematical rendering rules from the root protocol.md to a more organized docs/03_rendering_protocol.md and removed the old file. This centralizes all documentation for easier maintenance.

Feature: Added a final "Key Takeaways" slide.
Rationale: To bridge the gap between statistical theory and practical application. This slide explicitly explains how to interpret the confidence interval (especially regarding the value of zero) to make a meaningful, evidence-based conclusion. It serves as the capstone of the lesson.

Feature: The theoretical slides were completely rewritten to be more intuitive and narrative-driven.
Rationale: The previous slides were too formula-focused. The new content adopts a "scaffolding" approach, introducing concepts with intuitive questions and plain-English explanations before showing the formulas. This builds a stronger conceptual understanding.
Change: Replaced a dry review of formulas with a logical story that flows from a core question, through a "game plan," to a final synthesis.

Feature: Replaced the simple calculator with a multi-step Interactive Worksheet.
Rationale: The original calculator did the work for the student. The new worksheet requires active participation, forcing students to apply the formulas themselves to better internalize the material.
Change: The Calculator.tsx component was completely refactored to include input fields for each step of the calculation, a "Check My Work" button for immediate feedback, and a "Reset" function. The slide content was updated to introduce this new interactive element.

Refactor: Removed all caching logic and associated files (common/ folder, useKatexCache.ts).
Rationale: To simplify the codebase and remove unused functionality.
Standardization: Enforced a strict Unicode-only policy for all mathematical symbols. Replaced all hyphen-minuses (-) in mathematical contexts with the proper Unicode minus sign (−, U+2212) for correctness and consistency.
Cleanup: Removed obsolete React v17 script tags from index.html.

Feature: A functional slide-based learning module created from academic requirements.
Components: Included a title page, content pages with formulas, a basic calculator, and a quiz.
Tech: Built with React and TypeScript.