Metric driven documentation
summary
Claims that readability metrics measurably reduce cognitive load and help reviewers and translators, supported by a two‑year experiment. Built an open‑source GitHub Action called Lexi that preprocesses Markdown, runs five readability indexes, and reports a weighted score out of 100. Target score for technical docs lands around 60–70. Small rewrites regularly move scores by measurable amounts (examples given of +4, +2, +5, +1.34 points). Action runs on pull requests and reports regressions but does not block merges.
AI-written summary · about
chapters (8)
- 0:00Metric driven docs intro
- 1:04Readability metrics matter
- 3:33Docs cognitive load
- 8:10Readability reporter tool
- 16:32Lexi GitHub action
- 21:06Lexi markdown scoring
- 24:41Closing remarks
- 25:03Q&A
related talks
13mTechnical documentation – how can I write them better and why should I care?
39mLower the Barrier of Entry: Empowering Non-writer Contributions To Docs
27mInchJS: How to get people excited about inline docs
34mProving and improving the value of your docs
53mUsing Metrics to Take a Hard look at your code
29mHumanizing Your Documentation
28mActionable insights vs ranking How to use and how NOT to use code quality metrics
40mDocs Tools for OSS Maintainers