ds-notebook-readability

Improve notebook readability by adding intent-focused markdown notes and docstrings that explain non-obvious analytical choices, assumptions, and decision logic without restating syntax. Target explanations at long cells, transformations, metrics, and authoritative outputs so reviewers can interpret results.

Document analytical intent in notebooks by explaining inputs, grains, denominators, edge cases, and interpretation boundaries. Ensure authoritative outputs and dependencies are clear so another analyst can understand the methodology and decision rules.

Write effective notebook comments by adding concise markdown notes and block comments that explain non-obvious analytical choices and assumptions. Avoid syntax-only comments and instead target explanations where correctness and intent are needed for handoff.

Add documentation to a notebook for peer review when long cells, metric sections, transformations, joins, and aggregations lack explanations of analytical intent. Perform a handoff pass to ensure a new analyst can interpret diagnostic steps and conclusions.

Ensure notebooks are ready for handoff by performing a handoff pass over transformations and export steps to add the minimum necessary explanations. Target explanations at decision logic and authoritative outputs so another analyst can reuse the analysis.

Limitations of notebook explanations include targeting only non-obvious analytical choices rather than every cell, avoiding syntax-only comments, and ensuring the minimum necessary explanations are added so correctness and intent are visible without creating reading friction.