From tourist to homeowner
Session 1 gave you the map and a profile README made with someone else's recipe. Today you learn the recipe itself: how to create a repository like someone who has done it fifty times, why the README is the highest-leverage page you will ever write, and the small Markdown dialect that powers millions of handbooks, wikis and docs. This is the session where your running artifact - the team handbook repo - is born.
Create a repo like a pro 4 min live
One form, five decisions, thirty seconds. The + button in the top-right corner of any GitHub page is where every repository begins. A repo is three things at once: a folder (the files), a memory (every version, forever), and a front door (the README). The form decides how all three start.
LiveThe five fields, and what pros do with them3 min▶
- Name: lowercase-with-hyphens, meaningful, no dates or versions ("team-handbook", not "TeamHandbook_v2_2026"). It becomes part of a URL, so treat it like one.
- Description: one honest line. It appears in search results and on your profile - "Everything new joiners need, in one place" beats a blank.
- Public vs private: public means the whole internet can read (only invited people can change); private means invisible except to invitees. Handbooks and portfolios go public; anything with names, numbers or client details goes private.
- Add a README: ALWAYS tick it. Without it your new repo greets you with setup instructions written for developers; with it you land on an editable front page.
- Everything else: ignore. .gitignore and license pickers are tech-track business.
Self-studyPublic or private? The decision guide2 min read▶
| You are making... | Choose | Because |
|---|---|---|
| Team handbook, style guide, templates | Public | nothing sensitive + findability is the point |
| Your portfolio, course notes, profile README | Public | it is your shop window - let people in |
| Meeting notes, plans with names or numbers | Private | people and money stay behind the door |
| Client work, anything under NDA | Private | contractual, not optional |
| Not sure yet | Private | you can flip to public later in Settings; un-publishing is messier |
One rule with no exceptions: passwords, keys and secrets never go in ANY repo, public or private. Session 6 covers safety properly.
README: the front door 4 min live
The README is the page every visitor sees first, rendered right under your file list. Great ones all answer the same four questions in the first screen: what is this (one line), who is it for, how do I use or navigate it, and who owns it. Everything else is bonus.
LiveThe four questions + the pencil that answers them3 min▶
Editing happens entirely in the browser: open README.md, click the pencil ✏️, type, flip to the Preview tab to see it rendered, then press Commit changes and write a short message describing what you did. That message is not bureaucracy - it is a note to future-you.
- What: "The single source of truth for how our team works." One line, top of the page.
- Who: "For new joiners first, everyone second."
- How: a short list of links to the pages inside (your table of contents).
- Owner: a name. Unowned documents rot.
The awesome-lists phenomenon: some of the most-starred repositories on all of GitHub - "awesome" and "free-programming-books", each with 300k+ stars - contain no software whatsoever. They are ONLY a README: a beautifully organized list of links, maintained by thousands of people through proposals and reviews. Proof that a text-only repo can out-star almost every app on earth - and that the skills in this session are the whole game.
Self-studyCommit messages: notes to future you2 min read▶
Six months from now, someone (probably you) will scroll the history asking "when did this change, and why?" The message is the only thing standing between them and archaeology.
| Weak message | Strong message |
|---|---|
| update | clarify expense policy for travel under $50 |
| changes | add onboarding checklist for week one |
| fix | correct the HR contact email |
The recipe: start with a verb, say what changed and (if not obvious) why. Ten words is plenty. "clarify expense policy" beats "update" every single time someone searches the history.
Markdown in 15 minutes flat 7 min live
Markdown is plain text with a few punctuation marks that mean formatting. No toolbar, no fonts menu - which is exactly why it never breaks, diffs beautifully, and became the writing system of GitHub, Notion, Slack and half the internet. Here is the 95% dialect; you will be fluent before the apply-along.
LiveThe 95% dialect, one table4 min▶
| You type | You get |
|---|---|
# Title · ## Section · ### Sub | headings, three sizes - your document skeleton |
**bold** · *italic* | bold and italic |
- item (indent two spaces to nest) | bullet lists, nested as deep as you like |
[Ask Sam](https://...) | a clickable link |
| drag an image into the editor | GitHub uploads it and writes the image code for you |
`Settings` (backticks) | inline code style - perfect for filenames and button names |
> quoted line | an indented quote block |
| Day | Focus | rows with pipes | a real table (header row, then |---|---|, then rows) |
- [ ] task · - [x] done | real rendered checkboxes - free todo docs for non-tech teams |
:sparkles: | emoji ✨ - hundreds of codes work |
Self-studyGitHub-flavored extras: the social markdown2 min read▶
On GitHub, Markdown grows superpowers that plain text editors do not have. You will meet all of these properly in Sessions 3 and 4:
- Task lists in issues:
- [ ]inside an issue shows a live progress bar on the issue list. Project management for free. - @mentions: type
@usernameand that person gets notified - Markdown that taps shoulders. - #issue-links: type
#12and GitHub auto-links to issue 12. Cross-referencing without URLs. - Collapsible details: wrap long content so readers expand only what they need (this very card is the same pattern).
Optional deep end: the official Skills course Communicate using Markdown (github.com/skills/communicate-using-markdown) - 30 min, hands-on, same dialect.
Create the handbook repo ★ 6 min · everyone creates
Top-right + button → New repository. Name it team-handbook (or your real team's name, lowercase-with-hyphens). Description: one honest line about what it is.
Choose Public (it is a practice handbook - nothing sensitive goes in), tick Add a README file, click the green Create repository button. Your running artifact for the rest of this course now exists.
Click the pencil ✏️ on the README and write the four-line front door: what this is (1 line), who it is for, how to navigate (a placeholder list is fine for now), and who owns it (you).
Press Commit changes with a real message - "write the handbook front door" - not "update". Future-you says thanks.
The Markdown playground ★ 10 min · everyone plays
Type on the left, watch it render on the right - the fastest way Markdown has ever been learned. Recreate your handbook's front page here, then ship it for real.
Build your front page in the playground: one # title, one intro paragraph with **bold**, one ## section, and a 3-item list where one item is a [link](url).
Add one table with 2 columns: | Day | Focus |, the |---|---| divider row, then two or three rows. Watch it snap into a real table on the right.
Happy with it? Copy your playground text, open your real README with the pencil ✏️, paste it in, check the Preview tab, and commit with a message like "add navigation and weekly focus table".
Upgrade your profile README ★ 6 min · everyone upgrades
Open the username repo you made in Session 1 (github.com/you/you) and click the pencil ✏️ on its README - two honest lines are about to become a page.
Give it today's treatment: a # heading with your name, a short intro paragraph, and a "What I am working on" list with 2-3 items.
Add one flourish: a small table (projects and their status) or a > quote you live by. One is plenty - profiles reward restraint.
Commit ("give the profile a proper front page"), then visit your profile and admire. This page is live on the internet and you wrote it in a markup language. Today.
Recruiters and collaborators really do land on these pages. A profile README with a clear heading, one honest paragraph and a current-work list signals "this person ships and communicates" better than most CVs manage in two pages.
This week ◐ 25 min total
- Grow the handbook: add 2 real pages via Add file → Create new file. Name them like URLs:
onboarding.md,how-we-meet.md. Use headings, a list and at least one checkbox list. - One commit per page, each with a proper message ("add onboarding checklist", "document meeting rhythm"). Then open the history and enjoy reading your own trail.
- Read one awesome-list: search GitHub for "awesome" plus your field (awesome-analytics, awesome-product-management). Notice it is pure README + Markdown - then star it.
- Optional deep end: the Skills course Communicate using Markdown (github.com/skills/communicate-using-markdown).
Three questions before you go 🎯 ◐ 90 seconds
1 · Your team handbook has no names, numbers or client details, and you want new joiners (and candidates!) to find it. Public or private?
Public when nothing is sensitive AND being found is a feature; private when people, money or clients appear. When unsure, start private - you can flip it later in Settings.
2 · Why do commit messages like "clarify expense policy" beat "update"?
The history is only as useful as its notes. Six months from now, "update" x 40 is archaeology; verb-first messages are a searchable story of the document.
3 · Which Markdown gives you a real, rendered checkbox?
The dash makes it a list item, the brackets make it a checkbox: - [ ] open, - [x] checked. Inside issues these even show progress bars - Session 3 uses that.
Official GitHub Skills coverage
This course maps to GitHub's own free Skills exercises - each session tells you honestly what is covered here and what the official course adds.