# Plain-language — accumulated knowledge Append-only across sessions. Each entry records a recurring jargon problem and how to fix it. ## Format ``` ## YYYY-MM-DD — Story: Pass: ``` --- ## 2026-05-29 — "proclivity decile" → "student-body challenge group" Story: punching-above-50 Pass: 8 Our internal term "proclivity decile" combines three demographic inputs (% economically disadvantaged, % English learners, % students with disabilities) into a 1-to-10 ranking. Replace with "student-body challenge group (1 = easiest to serve, 10 = hardest to serve)" with inline definition the first time it appears. The 1-10 ranking still works; the abstract noun "decile" is what kills readability. ## 2026-05-29 — "residual" → "gap above expectation" Story: punching-above-50 Pass: 8 "Proclivity-adjusted residual" or "residual" alone is the most- flagged jargon term across stories. Replace with "gap above expectation" with the inline definition: "the school scored N percentage points higher than the typical school in its group." ## 2026-05-29 — "elementary academic composite" → "overall elementary-school score" Story: punching-above-50 Pass: 8 "Composite" reads like a chemistry term. Replace with "overall elementary-school score" and define inline once: "an average of grade-3 through grade-5 math and reading proficiency." ## 2026-05-29 — All-caps admissions categories need inline definitions Story: punching-above-50 Pass: 8 ZONED / OPEN / SCREENED / COMPOSITE all-caps reads like database column headers. Convert to title case (Zoned, Open, Screened, Composite) and add an inline glossary in the table caption the first time these appear: "Zoned = the kid attends because they live in the neighborhood. Open = any New York City student can apply. Screened = the school selects students by grades, attendance, or a test. Composite = a mix." ## 2026-05-29 — Spell out NYC, NYS, FOIL, DOE on first use Story: punching-above-50 Pass: 8 Even the obvious ones. "NYC" → "New York City." "NYS" → "New York State." "FOIL" → "Freedom of Information Law." "DOE" → "Department of Education." After the first appearance, the short form is fine. ## 2026-05-29 — "Cohort noise" / "cohort composition" → plain language Story: punching-above-50 Pass: 8 "Cohort noise" is jargon for "the makeup of one grade can vary year-to-year and affect the average score." Translate to that, or shorter: "looking at one year alone can mislead: a school can have a great year, or a bad year, just because of which kids happen to be in that grade." ## 2026-05-29 — Size every number with a comparison Story: punching-above-50 Pass: 8 "+30 percentage points" alone is meaningless to most readers. Size it: "+30 percentage points — roughly three letter grades higher." "+9.7 citywide" → "the city as a whole gained 9.7 points over six years." Comparisons should be either letter grades, the citywide average, or the size of the underlying population. ## 2026-05-29 — "Chronic absenteeism" needs an inline definition on first use Story: covid-absenteeism-stuck Pass: 8 The single most-used technical term across NYC ed-data stories. Standard NY State definition: a student who misses 10% or more of school days in a year. First use should say "chronically absent — meaning they missed at least 10% of the school year" (or similar). The term itself is kept because it's the official metric, but never left undefined. ## 2026-05-29 — "Percentile" / box-and-whisker → describe in the caption Story: covid-absenteeism-stuck Pass: 8 p10 / p25 / p50 / p75 / p90 are statistical shorthand and read as gibberish to most. In the chart caption: "bar shows the middle half of schools; lines extend to the top and bottom 10%." In the prose, replace "p10-p90" with "the range from the worst-attending 10% of schools to the best-attending 10%." ## 2026-05-29 — "D75" → "District 75" with inline definition Story: covid-absenteeism-stuck Pass: 8 District 75 is NYC's citywide system of schools for students with significant disabilities. Spell out and define inline first use: "District 75 (the citywide system of schools for students with significant disabilities)." After that, "District 75" is fine. ## 2026-05-29 — "Linear extrapolation" → "straight-line projection" Story: covid-absenteeism-stuck Pass: 8 A common quant addition that needs translation. "Straight-line projection" carries the same meaning and reads to a general audience. ## 2026-05-29 — "D18 / D19" district shorthands → "District 18 / District 19" Story: covid-district-18-comeback Pass: 8 Always spell out "District" — even when the rest of the prose references the same district many times. The "D" + number form looks like a battleship coordinate to a non-NYC reader. ## 2026-05-29 — "ARP" → "the American Rescue Plan (federal pandemic-relief funding)" Story: covid-district-18-comeback Pass: 8 Define this on first use. Most readers don't recognize ARP as the specific federal program; even those who do may not know which years the money flowed in. ## 2026-05-29 — "Scale score" → "raw test score" with parenthetical Story: covid-test-recalibration Pass: 8 The technical name (scale score) is preserved once parenthetically so readers who encounter it elsewhere recognize it. But in body text, "raw test score" is what works. ## 2026-05-29 — "Cutscore" → "cutoff" Story: covid-test-recalibration Pass: 8 Cutscore is education-industry jargon. Cutoff is normal English. The underlying concept (the score above which you're called proficient) should be defined in the first paragraph that introduces it. ## 2026-05-29 — "NAEP" needs full name + clarifier Story: covid-test-recalibration Pass: 8 On first use: "the federal NAEP test — given the same way in every state." After that, NAEP is fine. Critically, readers need to know NAEP is INDEPENDENT of the New York State test we've been discussing. ## 2026-05-29 — "ELL" → "students learning English" or named services Story: ell-gap-disaster Pass: 8 In prose, "students learning English" (or, when precision matters, "students currently in English-language services"). In data labels, the more precise form: "currently in English-language services" / "never needed English-language services." Long but readable. ## 2026-05-29 — "Subgroup" → "group of students" Story: ell-gap-disaster Pass: 8 "Subgroup" reads like database / statistical jargon. "Group of students" or just "students" with a modifier always works better. ## 2026-05-29 — Define ENL on first use; use parenthetical Story: ell-gap-disaster Pass: 8 "the program is called English as a New Language, or ENL" is the pattern. Just "ENL" alone is opaque to most readers. ## 2026-05-29 — Box-and-whisker chart caption must explain the chart Story: punching-above-50, covid-absenteeism-stuck Pass: 8 When using the distribution component, the caption should ALWAYS contain a one-clause explanation of what the bar and lines mean: "bar shows the middle half of schools; lines extend to the top and bottom 10%." Otherwise readers think the bar is the average.