GitHub Profile README
Profile setup, section order, project descriptions, and open-to-work statements
GitHub profile README essentials
- Setup: create a repo named exactly like your username — the README.md displays on your profile
- Structure: About me → What I work on → Featured projects → Contact
- Project formula: Name + what it solves + technology + social proof (users, stars, production use)
- Skills: primary / secondary / familiar with — don't list 10 languages as equals
- Open to work: seniority + stack + domain + location + contact email
Question 0 of 5
What is the correct location for a GitHub profile README to appear on your profile page?
Username-named repo + README.md in root is the magic combination. How it works:
- GitHub username:
johndoe - Repository:
johndoe/johndoe - File:
README.mdat the root of that repo - Result: GitHub displays that README on your public profile page
Which GitHub profile README section order is most effective for a job-seeking developer?
Professional identity → technical focus → proof → contact is the most effective order. GitHub profile README structure:
- About me (1–2 lines): who you are and what you build — "Senior Go engineer building developer tooling at scale"
- What I work on: your technical focus, specialisation, current projects
- Featured projects: 2–3 pinned repos with one-line descriptions — your proof
- Contact / Open to work: email, LinkedIn, Twitter/X, "Open to roles" if applicable
Which project description in a GitHub profile README is most effective?
Name + what it does + technology + social proof is the complete formula. Project description breakdown:
- Name: "dbmigrate" — bold, clear
- What: "zero-downtime PostgreSQL migration runner" — the problem it solves in 5 words
- How: "in Go" — the tech stack
- Proof: "used in production by 40+ teams" — social proof beats stars
A developer writes: "I know Python, JavaScript, TypeScript, Go, Rust, Ruby, Java, C++, PHP, and I am currently learning Kotlin and Dart." What is wrong with this?
Breadth without depth — lists every language, differentiates none. How to structure technology skills:
- Primary (expert/daily): Go, TypeScript — languages you'd use in a job interview
- Secondary (proficient): Python, Rust — you've shipped with these
- Familiar with: Java, C++ — you can read and understand, not write from scratch
- Learning: Kotlin, Dart — honest signal of growth direction
Which "Open to work" statement in a GitHub profile is most useful to recruiters?
Seniority + stack + domain + location + contact pre-qualifies every recruiter before they message you. Open to work statement elements:
- Seniority: "senior" — filters out junior role offers
- Stack: "Go/Rust" — filters out frontend or Python-only teams
- Domain: "distributed systems, fintech, developer tooling" — signals fit quickly
- Location: "remote or Berlin" — no wasted conversations about relocation
- Contact: direct email — lowest friction for inbound