How to Write a Data Analyst Portfolio README That Gets You Noticed

# How to Write a Data Analyst Portfolio README That Gets You Noticed Your GitHub repository is often the first thing a recruiter or hiring manager opens after your resume. A strong analysis with a weak README looks unfinished; a clear, well-structured README makes even a small project look professional. This guide walks through exactly how to document data analysis portfolio projects, using real examples from my own portfolio. ## Why the README matters more than the code Most people who open your repository will never run your code. They will skim the README for thirty seconds and decide whether you think like an analyst. A good README answers three questions fast: 1. **What problem did you solve?** 2. **How did you approach it?** 3. **What did you find?** Everything in your README should serve one of those questions. ## The structure that works ### 1. Title and one-line summary Start with the project name and a single sentence describing the outcome, not the tools. Compare: - Weak: "SQL project using joins and CTEs" - Strong: "Banking risk analysis identifying the customer segments most likely to default, using SQL and Power BI" ### 2. Problem statement Two to four sentences. Who has the problem, why it matters, and what a good answer looks like. In my Banking Risk Dashboard project, the framing is a bank that needs to understand loan default risk across customer segments — that context makes every technical choice that follows feel purposeful. ### 3. Data source and description State where the data came from, its size, and its key fields. If the data is public, link to it. If it is synthetic or anonymized, say so — honesty here builds trust. ### 4. Data cleaning steps This is where most READMEs fail. Do not just say "cleaned the data." List the actual decisions: - How you handled missing values (and why you chose dropping vs. imputing) - Duplicates removed and how you detected them - Data type corrections - Outliers: kept, capped, or removed — with reasoning Showing your reasoning proves you understand the trade-offs, which is what junior analyst interviews test. ### 5. Analysis approach Walk through your methodology in the order you did it. For SQL projects, include the most interesting queries in fenced code blocks with a sentence explaining what each one answers. For my SQL analysis work, I show the query that segments customers next to a plain-language explanation of the business question it answers. ### 6. Key findings Use a numbered list of three to five findings, each with a number in it. "Customers aged 25–34 with unsecured loans defaulted at 2.3x the portfolio average" is memorable; "younger customers default more" is not. ### 7. Visualizations Embed screenshots of your dashboards directly in the README. A Power BI or Tableau screenshot lets a reviewer see your visualization skills without opening anything. Caption each image with what the viewer should notice. ### 8. Tools and technologies A short bullet list: SQL (PostgreSQL), Power BI, Python (pandas), Excel. No paragraphs needed here. ### 9. How to reproduce Brief setup steps: where to get the data, which scripts to run in what order. Even if nobody runs it, its presence signals rigor. ### 10. What you would do next One short paragraph on limitations and next steps. This shows intellectual honesty and gives interviewers an easy question to ask you — one you have already prepared for. ## Common mistakes to avoid - **Walls of text.** Use headings, bullets, and tables. Reviewers skim. - **Tool-first writing.** Lead with the problem and findings, not the tech stack. - **No visuals.** A dashboard project with no screenshots is invisible. - **Generic descriptions.** "Analyzed data to find insights" says nothing. Be specific about what you found. - **Broken links and dead images.** Click every link before you share the repo. ## A quick checklist before you publish - [ ] One-line summary states the outcome - [ ] Problem statement gives business context - [ ] Cleaning decisions are explained, not just listed - [ ] At least three findings with specific numbers - [ ] Dashboard screenshots embedded and captioned - [ ] Reproduction steps included - [ ] All links tested ## Final thought Your README is a writing sample, a thinking sample, and a portfolio piece in one document. Treat it with the same care as the analysis itself, and your GitHub profile becomes one of the strongest parts of your job application. Want to see these principles in action? Browse my [projects](/work) — each repository follows this structure.