Writing a project case study

GitHub’s tutorial for job seekers expects a hiring manager to look at a project for a couple of minutes, and a case study of 700 words takes three and a half minutes to read at 200 words a minute. Many readers stop before the end, so a case study has to work for them too.

This lesson writes one for Meera’s canteen queue tracker: the parts a case study needs and the question each part answers, written in layers so that its first 30 words already hold the result.

A case study tells the reasoning a README leaves out

Open the canteen tracker’s repository and its README does what GitHub’s tutorial asks of one: it lists what the project can do, gives the steps to install and start it, shows a demo and explains how to run its tests. An interviewer’s questions start where it stops. Why a token queue and not a second counter? Why SQLite? How was the wait measured? A case studycase study: A short account of one project for a reader deciding whether to interview you: the problem and who had it, the constraints, the approach, the trade-offs, the results against a baseline and the next steps. answers them: it is the project’s reasoning, written down for a reader who was not there.

MySmartCoPilot’s template has seven parts, in this order, in 400 to 900 words:

Four things travel with the parts. Every image gets alt textalt text: A short text that stands in for an image: screen readers read it aloud, and it shows when the image cannot load. It says what the image shows. that says what it shows. A credits section names each teammate’s part, every library and any AI help. Work you cannot show, such as an internship’s internal system, is described in general terms, with ranges in place of confidential figures. And the last line links the code.

Write it in layers, because readers stop early

At a reading pace of 200 words a minute, a reader who gives your project two minutes reads 400 words. Write for that reader first, in three layers: a summary line of at most 30 words with the result; a card of up to 120 words for your portfolio page, with the problem, your part, the result and the link; and the full case study for the reader who stays. Step through what each reader takes away:

The program measures Meera’s first two layers, and checks that each one carries the result with its unit and that the card carries the link:

# The first two layers of a case study for Meera's canteen queue tracker: a summary line and a card for her portfolio
# page. The program counts the words of each layer, gives its reading time at an assumed pace of 200 words a
# minute and checks that the layer carries the result, with its unit, and, on the card, the link.
# Meera, her project and its address are invented. Press Edit, write your own layers in LAYERS, and run it again.
import re

WORDS_A_MINUTE = 200
RESULT = re.compile(r"\b\d+(?:\.\d+)? to \d+(?:\.\d+)? (?:minutes|seconds|ms|%)")
LINK = re.compile(r"github\.com/[\w.-]+/[\w.-]+")

LAYERS = {  # name: (most words, needs the link, text)
    "summary line": (30, False, "Canteen queue tracker: a token queue for my college canteen, built with two "
                                "classmates in Flask and SQLite, that cut the average lunch-hour wait from 14 to 6 "
                                "minutes."),
    "card": (120, True, "Canteen queue tracker · Flask, SQLite · with two classmates. The college canteen sells about "
                        "450 lunches a day from one counter, and at lunch the queue took 14 minutes. We built a token "
                        "queue: students take a numbered token on a tablet and sit down until the counter screen "
                        "calls them. My part was the queue itself and its 31 tests. Over four weeks of use, the "
                        "average lunch-hour wait fell from 14 to 6 minutes, measured from the app's own log against "
                        "a week of timing by hand before it. Next: a pause button the staff asked for. Code and "
                        "demo: github.com/meera-iyer-example/canteen-queue"),
}


def words(text):
    return re.findall(r"[\w'’./:-]+", text)


for name, (most, needs_link, text) in LAYERS.items():
    n = len(words(text))
    checks = [f"result with its unit: {'yes' if RESULT.search(text) else 'missing'}"]
    if needs_link:
        checks.append(f"link: {'yes' if LINK.search(text) else 'missing'}")
    over = "" if n <= most else f" (over the limit of {most})"
    print(f"{name}: {n} words{over}, {round(n * 60 / WORDS_A_MINUTE)} s to read · {' · '.join(checks)}")

print(f"full case study: 400 to 900 words, {400 / WORDS_A_MINUTE} to {900 / WORDS_A_MINUTE} min to read")
print(f"what a reader gets through in two minutes: {2 * WORDS_A_MINUTE} words")

summary line: 29 words, 9 s to read · result with its unit: yes
card: 102 words, 31 s to read · result with its unit: yes · link: yes
full case study: 400 to 900 words, 2.0 to 4.5 min to read
what a reader gets through in two minutes: 400 words

Both layers fit their limits: 29 words in about 9 seconds, and 102 words in about 31. The summary line names the result, the wait falling from 14 to 6 minutes, so a reader who stops there still has it. The full 400 to 900 words take 2 to 4.5 minutes, so the problem and the approach come before the detail.

The canteen tracker's case study, written section by section Pro: opens with a Pro, Premium or Ultimate pass

Alt text, credits and work you cannot show Pro: opens with a Pro, Premium or Ultimate pass

A rubric for judging a case study, level by level Pro: opens with a Pro, Premium or Ultimate pass

Practise: fix a case study draft

Arjun, the invented student of this track’s project entries, wrote a hurried case study for his library seat booker. Fix it from his records; the sample tests check the summary line, the seven sections, the length, the numbers, the result, the alt text, the credits and the link:

# Arjun's case study draft, written in a hurry. Fix it from his records in the prompt.
CASE_STUDY = """# Library seat booker

A seat booking site I made for my college library. It works really well and students like it.

## Problem

The reading room of our college library was always full during exams, but many seats had a bag on them and nobody in
them. Students booked seats by writing their name in a register at the desk, and there was no way to know whether
anyone would come. Students who needed a seat were turned away at the door while booked seats stood empty for
hours, and the librarian spent a lot of time settling arguments about who had booked what. I wanted to see
whether a simple booking site could free up those seats without making more work for the library staff.

## Approach

I built a website where a student picks a seat and a time slot. When the student arrives, they check in at the desk,
and the site marks the seat as taken. If nobody checks in, the seat goes back into the pool so that someone else can
book it. The librarian has a page that shows every seat, its bookings for the day and which ones are checked in, and
can release a seat by hand if something goes wrong. I kept the pages simple so that they load quickly on a phone and
work on the old computer at the desk.

![screenshot](images/seat-map.png)

## Results

No-shows went down a lot and the librarian was happy with it. Students also stopped arguing at the desk about who
had booked a seat first.

## Next steps

I would like to add a waiting list, so that a student is told by e-mail when a seat comes free, and a weekly report
for the librarian that shows how full the reading room was at each hour of the day.
"""

import re

from case_study import CASE_STUDY

SECTIONS = ["Problem", "Constraints", "Approach", "Trade-offs", "Results", "Next steps", "Credits"]
RECORDS = (
    "120 seats; 31 % of booked seats never used; a 2-hour slot; released 15 minutes after its slot starts, rather "
    "than 30; no-shows fell from 31 % to 12 % over one semester"
)
NUMBER = re.compile(r"(?<![\w.,/-])\d+(?:\.\d+)?(?![\w/])")
IMAGE = re.compile(r"!\[([^\]]*)\]\([^)]*\)")
LINK = "https://github.com/arjun-mehta-example/seat-booker"
RESULT = re.compile(r"from \d+(?:\.\d+)? ?(?:%|minutes|seconds)[^.]*?\bto \d+(?:\.\d+)? ?(?:%|minutes|seconds)")


def section(name):
    parts = re.split(r"^## ", CASE_STUDY, flags=re.M)
    for part in parts[1:]:
        title, _, body = part.partition("\n")
        if title.strip() == name:
            return body
    return ""


def prose():
    text = IMAGE.sub(" ", CASE_STUDY).replace(LINK, " ")
    return re.findall(r"[\w'’.-]+", text)


def test_summary_line_names_the_result():
    """opens with a summary line of at most 30 words that names the result with its unit"""
    before = CASE_STUDY.split("\n## ", 1)[0]
    lines = [line for line in before.splitlines() if line.strip() and not line.startswith("#")]
    assert lines, "write a summary line before the first heading"
    summary = " ".join(lines)
    assert len(summary.split()) <= 30, f"the summary line has {len(summary.split())} words: at most 30"
    assert re.search(r"\d+ ?%", summary), "the summary line names the result with its unit"


def test_seven_sections_in_order():
    """has the seven sections as ## headings, in order"""
    headings = [h.strip() for h in re.findall(r"^## (.+)$", CASE_STUDY, flags=re.M)]
    assert headings == SECTIONS, f"the headings are {headings}: they should be {SECTIONS}"


def test_length_and_numbers_from_the_records():
    """is 400 to 900 words long, and every number comes from the records"""
    words = prose()
    assert 400 <= len(words) <= 900, f"{len(words)} words: write 400 to 900"
    allowed = set(NUMBER.findall(RECORDS))
    found = set(NUMBER.findall(IMAGE.sub(" ", CASE_STUDY).replace(LINK, " ")))
    assert found <= allowed, f"numbers that the records do not hold: {sorted(found - allowed)}"


def test_result_with_baseline_and_unit():
    """gives the result in Results with its baseline and its unit"""
    assert RESULT.search(section("Results")), "write the result as 'from <baseline> to <result>', with the unit"


def test_alt_text_and_credits_and_link():
    """gives every image useful alt text, credits in three lines, and the link to the code"""
    for alt in IMAGE.findall(CASE_STUDY):
        assert len(alt.split()) >= 5, f"the alt text '{alt}' does not say what the image shows"
    credits = section("Credits")
    for start in ("Team:", "Libraries:", "AI help:"):
        assert re.search(rf"^\s*(?:- )?{re.escape(start)}", credits, flags=re.M), f"the credits need a line '{start}'"
    assert LINK in CASE_STUDY, "link the code"

Then answer questions on the parts and the layers of a case study, starting with the idea you have answered worst so far:

Interview questions

Warm-up (fresher to mid-level): How does a project’s README differ from its case study?

The README tells a visitor how to use the project: what it does, how to install and start it, where to see it working, and how to test it. The case study tells a reader why it was built that way and what it changed: the problem, the constraints, the approach, the trade-offs with their costs, the results against a baseline and the next steps. The README serves someone who wants to run the code; the case study serves someone deciding whether to interview you, so it starts with the result and says which part was yours.

Three questions of this module’s bank go further:

Key takeaways

• A README says how to run a project; a case study says why it was built that way and what it changed, in seven parts from the summary line to the next steps.
• Write in layers: a summary line of at most 30 words with the result, a card of up to 120 words, then the full case study of 400 to 900 words.
• A reader who gives a project two minutes reads about 400 words, so the result and the problem come first.