Case Study 1 — Raj's README Makeover: A Full Before-and-After

This case study walks through the anchor example of the chapter—Raj Patel's chronoparse README—from the symptom that triggered the rewrite to the finished front door. Read it as a worked example of the diagnosis-then-fix move: see the failure, name exactly what's wrong, watch the fix, and notice what changed. chronoparse is fictional but realistic; the failure pattern is one you'll find in thousands of real repositories.

The symptom

Raj didn't set out to rewrite anything. He opened his issue tracker on a Monday and read, in order, the same question filed eleven times across eighteen months: "How do I install this?" Then a twelfth, sharper: "Is this dead? Couldn't figure out how to get started, so I wrote my own."

That last issue is the one that stung, because it named the cost precisely. Raj's library worked. The code was good. But a developer had wanted it, failed to get in the door, and rebuilt it from scratch—wasted effort on both sides, traceable entirely to the README. Eleven people had stood at the front door and found it locked.

The first lesson of the makeover is diagnostic: the issue tracker was telling Raj exactly what his documentation was missing. Eleven "how do I install this?" issues are not eleven confused users; they are one missing installation section, reported eleven times. The repeated question is the spec for the fix.

The diagnosis

Here is what a visitor met (abridged from the chapter's full reproduction):

"Parsing dates is one of the most deceptively difficult problems in software engineering. Human beings express time in an astonishing variety of ways… The core philosophy behind chronoparse is that date parsing should be forgiving by default but strict when you ask it to be… Under the hood, chronoparse uses a tokenizer that breaks an input string into candidate temporal tokens, followed by a grammar-driven parser…"

Eight hundred words, and Raj could defend every sentence—it's accurate, it's thoughtful, it's even well-written. That's exactly the trap. The README failed not because it was bad prose but because it was the wrong content in the wrong order. Run the diagnosis against the questions a visitor actually arrives with:

The two questions that matter most—install and example—got no answer. Raj had written for himself (the internals fascinated him) instead of for the stranger at the door (who just wanted in). That's the curse of knowledge wearing a software costume: the things Raj found interesting were not the things his reader needed.

The fix

Raj didn't write more. He wrote what the visitor needs, in the order they need it, and moved the philosophy out of the doorway. He restructured around the reader's questions:

# chronoparse

[![build](…)]() [![pypi v2.1.0](…)]() [![license MIT](…)]()

**chronoparse turns human date strings ("next Tuesday," "3 days ago") into
Python `datetime` objects.**

Most date libraries handle ISO strings and give up on the messy way dates
actually appear in user input, logs, and scraped text. chronoparse handles both.

## Features
- Parses relative, absolute, and colloquial dates
- Resolves against any reference time, not just "now"
- Time-zone aware · Extensible grammar · Zero core dependencies

## Installation
```bash
pip install chronoparse

Requires Python 3.8+.

Quick start

from chronoparse import parse
parse("next Tuesday")   # → datetime(2024, 6, 11, 0, 0)
parse("3 days ago")     # → datetime(2024, 6, 5, 14, 30)

Documentation · Contributing · License

Full reference · CONTRIBUTING.md · MIT ```

Five changes did the work:

1. A one-line description that contains examples ("next Tuesday," "3 days ago")—a visitor knows in five seconds whether this matches their problem.
2. The philosophy shrank to two sentences under the one-liner, where it motivates without blocking, and the internals (tokenizer, grammar engine) left the README entirely for the linked reference.
3. An installation section that is just the command—the fix for all eleven issues.
4. A runnable quick-start showing the call and the result—the single most persuasive thing a README can contain, and previously absent.
5. Informative headings (Features, Installation, Quick start) so the scanning developer jumps straight to their question.

The result

The rebuilt README is shorter than the original and immeasurably more useful—because usefulness was never about length. The "how do I install this?" issues stopped. New users converted, because they could copy three lines, watch them work, and trust the tool.

The deeper lesson is the chapter's threshold concept, made concrete: for everyone who wasn't Raj, the README was the library. The elegant parsing code behind it was unreachable until the front door opened. The makeover didn't change a line of that code; it changed whether anyone could get to it.

Try it yourself: Find a README you wrote (or could write) for something you've built. Run the same diagnosis table—does it answer each of the visitor's five questions? Then run the clean-machine test: follow your own install and quick-start on a fresh setup, with literal obedience, and fix every place you have to improvise. The stalls are your eleven issues, found before anyone files them.

Back to: Chapter 25 · Case Study 2 · Key Takeaways