Search⌘ K
AI Features
Home
Courses
Forward Deployed Engineer for AI Systems

Writing the README

Explore how to lead a README with the customer outcome and the shortest verification route. Understand how to label expected, reported, and personally observed results, and how to document failure behavior and boundaries, preparing you to write handoffs a reviewer can follow and check.

We'll cover the following...

These are the two questions a fictional invoice-review handoff must answer.

“Which invoices need follow-up?”

“How can I reproduce that answer?”

An accounts-receivable coordinator needs a locally generated list of overdue, unpaid invoices for manual follow-up. Stakeholders need to understand the user's task, expected output, and workflow limitations. Engineers also need input requirements, execution commands, filtering rules, and verification steps.

A README should explain the customer's task and provide a reproducible workflow that reviewers can verify independently. Setup instructions alone do not explain the project's purpose, while a project description without execution and verification steps does not establish reproducibility.

Structuring the README

Put the customer outcome and shortest verification route before implementation detail. A practical course structure covers:

  • Customer problem and intended value.

  • Approach and decision rules.

  • Prerequisites, setup, and usage.

  • Expected outputs and failure behavior.

  • Tests and their coverage limits.

  • Assumptions and operational boundaries.

Adapt that structure to the assignment’s requested artifacts. It is not a mandatory employer template.

Public take-home guidance recommends working code, sensible structure, edge-case handling, and concise explanations of assumptions and choices. It does not establish a universal scoring weight for README quality.

Gathering delivery facts first

Start with delivery facts rather than adjectives. For this writing exercise, the fictional delivery packet stipulates:

  • Runtime: Python 3.11 or later, standard library only.

  • Files: invoice_review.py, samples/invoices.csv, samples/invoices_bad.csv, and test_invoice_review.py.

  • Execution: Commands run from the repository root. The program creates the output directory.

  • Rule: Select unpaid invoices whose due_date is strictly before the supplied --as-of date, preserving source order.

  • Writing: Validate the entire input before writing; ...