Ian Klosowicz
Most analysts building portfolio projects don't write a README at all. The ones who do write one usually write it for themselves — technical notes, file descriptions, setup instructions no one will follow. Neither version gets read by a recruiter or hiring manager.
A README a recruiter will actually read is short, skimmable, and leads with what matters to someone who is not a data analyst: the question, the finding, and the business context. Everything else is secondary. This post covers the structure, the common mistakes, and a template you can use for any analytics project.
The typical analytics portfolio README opens with the project title, then immediately goes into technical setup: "Clone the repository. Install dependencies. Run the following commands." Nobody hiring an entry-level analyst is going to run your code locally. They're going to skim the page for 30 seconds and decide whether to look at the actual work.
A README that leads with setup instructions was written for a developer audience, not a hiring audience. The same mistake shows up in a different form when the README is a wall of text explaining the data source in exhaustive detail before saying anything about what the project found.
Recruiters and hiring managers at the entry level are not reading for technical depth in the README. They're reading to understand whether the project is worth clicking into. If the README doesn't answer that question in the first 3 to 5 lines, they're gone.
Before writing a word, understand what a non-technical reviewer is trying to learn from your README:
That's the full list. A README that answers all 4 of those in under 200 words has done its job. Anything beyond that is for the hiring manager who is already interested and wants to go deeper — and even then, it should be scannable, not dense.
Technical reviewers — the people who will actually look at your SQL or your data model — will find what they need by reading the code, not the README. The README is a front door, not a technical specification.
A portfolio project README has 2 jobs: get the non-technical reviewer interested enough to click the project link, and give the technical reviewer enough context to understand what they're looking at. Both jobs are served by the same structure, just read in different depths.
The sections, in order:
Sections 1 through 4 are for the recruiter. Sections 5 through 7 are for the technical reviewer. The whole thing should fit on 1 screen without scrolling on a laptop display. If it doesn't, it's too long.
This is the part that gets read and the part most people get wrong. The instinct is to introduce the project with background context — explaining why the topic is interesting, what motivated the analysis, what the broader data landscape looks like. None of that is what a recruiter needs.
The opening section should answer 3 questions in sequence:
What question did you ask? State it directly. "This project analyzes hospital readmission rates across US counties to identify which facility characteristics are most strongly associated with lower 30-day readmission." One sentence. Specific. The reviewer immediately knows what the project is and whether it's relevant to their context.
What did you find? State the key finding next, before anything else. "Facilities with a patient-to-nurse ratio below 5:1 had a 23% lower readmission rate on average, independent of facility size or patient complexity." This is the result that matters. If the recruiter reads only 2 sentences, they should be these 2.
Where did the data come from? One sentence naming the source and the scope. "Data sourced from CMS Hospital Compare, covering 4,800 hospitals across 3 reporting years (2020 to 2022)." This establishes that the data is real and gives the reviewer a sense of scale.
Those 3 elements — question, finding, source — in that order, in plain language, in under 100 words. That's the opening section. Write it last, after you've done the analysis and know what you actually found.
After the opening, the README can include technical details — but keep them scannable, not dense.
Tools used. A short, flat list. SQL (PostgreSQL), Power BI, Python (pandas). Not paragraphs describing what each tool does. The reviewer knows what SQL is. The list tells them what skills are demonstrated in the project.
Key methods or techniques. Optional, but useful for SQL and Python projects where the analytical approach isn't visible from a dashboard link. 2 to 3 bullet points is enough: "Cohort analysis using window functions to calculate 90-day retention rates" or "Joined 3 tables across patient, facility, and outcome dimensions." These signal analytical sophistication without requiring the reviewer to read the code.
Project structure. Optional for simple projects, useful for multi-file repos. A short list of the files and what each does: "queries/retention_cohort.sql — main cohort analysis" and "data/README.md — data dictionary and source notes." This helps a technical reviewer navigate without digging through every file.
How to view the work. A direct link to the live dashboard, the published notebook, or the key output. This should be impossible to miss. If someone reads your README and can't find the link to the actual project within 5 seconds, you've buried the most important element.
Most README content that doesn't help the hiring audience falls into a few categories worth cutting entirely.
Installation and setup instructions. Nobody hiring an entry-level analyst is going to clone your repo and run it locally. If you include setup instructions, put them at the bottom, after everything else. Don't let them appear anywhere near the top of the page.
Lengthy background context. "Data analytics has become increasingly important in the modern business environment" is not a README opening. Neither is a 3-paragraph explanation of the healthcare system before stating what the project found. Context can be 1 sentence. Background is almost always padding.
Technical jargon that explains nothing to a non-technical reader. "Leveraged advanced feature engineering pipelines to optimize model performance" means nothing to a recruiter and is vague even to a technical reviewer. Be specific: "Used CASE WHEN to create categorical bins for hospital size, then aggregated readmission rates within each bin." Specific and plain beats general and jargon-heavy every time.
Obvious statements about the data. "The dataset contains rows and columns representing hospital-level information." Skip it. Everyone knows what a dataset is.
Apologies or caveats upfront. "This is my first project and I'm still learning" in the README opening costs you before the reviewer has seen anything. If the work is good, it speaks for itself. If it isn't ready, don't publish it yet.
Use this as a starting point for any SQL or Python portfolio project. Fill in the bracketed sections with your project's specifics. Keep the whole thing to 1 screen.
[Project Title]
[One sentence describing what the project does and what domain it covers.]
The Question
[State the specific business question this project answers. 1 to 2 sentences.]
Key Finding
[State the main result. Be specific — include numbers where you have them. 1 to 2 sentences.]
Data Source
[Name the source, the scope (how many records, what time period), and where to find it. 1 to 2 sentences.]
Tools
[Tool 1], [Tool 2], [Tool 3]
Methods
View the Project
[Direct link to the live dashboard, notebook, or key output — make this the most visible element on the page.]
Files (optional)
[filename.sql] — [what it does]
[filename.ipynb] — [what it does]
That template covers every section a recruiter or hiring manager needs without padding. Write it after the analysis is done, not before — the finding section requires you to know what you found.
Building projects with this level of presentation discipline is part of what the Analyst Hive program covers in Month 1. The project itself and the way it's framed and presented are built together, not treated as separate tasks.
How long should a portfolio project README be?
Short enough to fit on 1 laptop screen without scrolling. In practice, that's around 200 to 350 words for most entry-level projects. The opening 3 elements — question, finding, data source — should take up the first half. Tools, methods, and the project link take up the second half. If your README is longer than 400 words, you've included something the hiring audience doesn't need.
Does a BI dashboard project need a README?
Not always, but it helps. Tableau Public and Power BI Service let you add a description to the published project, which serves a similar function. If your dashboard is hosted on GitHub alongside a .pbix file or PDF exports, a README is worth adding — it gives the reviewer context before they open the file. Keep it to the same structure: question, finding, data source, tools. Skip the setup instructions entirely for BI projects.
Should I write the README in first person?
Yes. "I analyzed" is cleaner and more direct than "The analysis examined" or "This project investigates." First person is appropriate, natural, and easier to read. Passive voice in a README reads as evasive and adds word count without adding information.
Do I need to include a data dictionary in the README?
Not in the main README, but it's worth including as a separate file if the dataset has non-obvious field names. Reference it from the README with a single line: "See data/data_dictionary.md for field definitions." A hiring manager won't read a data dictionary during the resume review; a technical reviewer might if they're interested in the project. Keep it separate so it doesn't clutter the main document.
What if my project didn't produce a clear finding?
Reframe it. A project that found "no significant relationship between X and Y" is a valid finding if the question was whether a relationship exists. State what you expected to find and what the data actually showed. If the project genuinely produced nothing useful, the problem is likely the question, not the data — go back and narrow the scope before publishing the work.
Should I include a license in the README?
For portfolio projects using public data, a standard MIT license or Creative Commons attribution notice is fine and takes 1 line. It's not necessary, and most hiring managers won't look for it. Include it if you want to signal that you understand open source conventions; skip it if it's not something you care about. It has no material effect on how the project is evaluated.
If you want a structured approach to building projects, writing READMEs, and framing your work on a resume in a way that actually gets read, the Analyst Hive program covers all of it in Month 1. Daily tasks, built around getting hired.
