Project kit

For an end-to-end analytics project: a course project, a portfolio piece, or a take-home for a job. A checklist by stage, a repository layout you can copy, what a reader looks for, and the ways projects usually go wrong. The stages follow the data science process.

The checklist, stage by stage

Tick an item only when it is true of the project as it stands today, not when you plan to do it. Each item is something a second person could open your repository and confirm. The ticks are saved in this browser, on this device, and nowhere else.

A repository template

One layout that works for a course project, a portfolio piece and a take-home. Copy it and delete what you do not need. The test of the whole thing: a stranger clones it, runs the one command in the README, and gets the number the report claims.

my-project/
├── README.md            # the question (one paragraph), the answer (one sentence), how to run it
├── requirements.txt     # pinned versions: pandas==2.2.2, not pandas
├── data/
│   ├── README.md        # source URL, date pulled, license, what you did not use and why
│   ├── raw/             # files exactly as downloaded, never edited
│   └── clean/           # files your code made from raw/
├── notebooks/
│   └── analysis.ipynb   # the analysis in order, ending with a "Headline numbers" cell
├── src/
│   └── project.py       # functions the notebook imports: load, clean, fit, each with a check
├── figures/             # every figure in the report, saved by a notebook cell
├── report.md            # or report.pdf: question, answer, the figure, method, limits, decision
└── ai-appendix.md       # what you asked, the replies as they came, what you kept, what you checked

README.md

The question in one paragraph. The answer in one sentence, with its number. How to run the project: the one command, and roughly how long it takes. "Run the notebooks in order" counts only if the order is stated and they tolerate it.

requirements.txt

Every package the notebook imports, each with the version you ran. A missing version is the usual reason a project works for you and for nobody else.

data/README.md

For each file: where it came from with the URL, the date you pulled it, the license, and what you did not use (variables dropped, years cut, rows removed) with the reason. If the license does not allow redistribution, say so and ship a download script instead of the file.

data/raw/, data/clean/

Raw is what you downloaded and never touch. Clean is what your code produces from it. If a reader deletes clean/ and reruns, it comes back the same.

notebooks/

The analysis, readable top to bottom, with a text cell before each section saying what it does. The last code cell is headed Headline numbers and prints every number in the report beside the cell that produced it.

src/

Functions the notebook imports: loading, cleaning, the fit, the figures. Each has a docstring and at least one assertion. Logic that lives in a function runs the same way every time; logic copied between cells does not.

figures/

Every figure in the report, saved by a notebook cell with savefig, named by what it shows. No figure that was pasted from a screenshot.

report.md or report.pdf

Question, answer, the one figure, how you got there, the limits, the decision it supports. The regression table and the diagnostics go in an appendix.

ai-appendix.md

If you used a model: the prompts as you sent them, the replies as they came back (not a summary), what you kept, what you changed and why, and how you checked what you kept. If you used none, one line saying so. A reader treats this as a record of how you work with these tools.

What a reader looks for in a portfolio project

A hiring manager or an instructor opens the repository with ten minutes and a question of their own: can this person take a question to a decision without someone standing over them? These are the things they check, roughly in order.

1. A question with a defensible answer. The README states the question in one sentence and the answer in the next. Everything else in the repository exists to support that second sentence.
2. The decision the analysis supports. Who would act differently because of this finding, and how. A project that ends at "further research is needed" has not finished.
3. One figure that carries the result. A reader who sees only that figure and its caption gets the finding. The axes have units, the comparison is in the picture, and it reads in black and white.
4. Limits stated by the author first. What the data cannot tell you, what you assumed, what would overturn the result. A reader who finds a limit you did not mention trusts the rest less.
5. Reproducibility. A clean clone, one command, the same number the report claims. Readers check this more often than students expect, and a different number ends the review.
6. Data provenance. Where the data came from, when, under what license, and what was dropped. It tells the reader you know what population your answer is about.
7. Code a reader can follow. Functions whose names say what they do, a notebook that reads top to bottom, no cell that only works if another cell was run twice.
8. Judgment about tools, including AI. The appendix shows what you asked, what you kept and how you checked it. Readers are not looking for zero AI; they are looking for someone who knows which parts of the answer they have confirmed.

Common ways projects fail

• The question changes halfway. The README asks one thing and the report answers another, and neither names the switch.
• The data cannot answer the question. No variation in the thing you care about, or the outcome is not measured for the population you named.
• A leak between train and test. Scaling, imputation or feature selection done on the full data before the split, so the test score is a flattering fiction.
• A report number the notebook never prints. Nobody can check it, including you a month later.
• A chart that cannot be read in black and white, or whose axis starts where the effect looks largest.
• No stated limits. The reader supplies their own and discounts everything else.
• It runs only on your machine. A path to your desktop, a package with no version, a cell that depended on one you ran earlier and deleted.

Where next