Markdown and a good README
On This Lesson 11 topics
Lesson Overview
When someone opens your repository on GitHub, the first thing they see below the file list is the README. It is your project's front door. A visitor, a teammate, or an interviewer decides in seconds whether your project looks worth their time, and whether they can run it at all.
A README is written in Markdown, a way of writing plain text with a few simple marks (a # for a heading, a - for a list item, backticks for code) that GitHub turns into nicely formatted pages. Markdown takes about ten minutes to learn.
In this lesson you will learn the Markdown you actually need, and the three things a README must contain: what the project is, how to set it up, and how to use it. The classic failure is a README with no setup steps, so the visitor cannot run anything. In the shared bookshelf picture, the README is the label on your album: it says what is inside and how to open it.
Learning Objectives
By the end of this lesson you will be able to:
- Write headings, paragraphs, lists, inline code, code blocks, links, bold, and italics in Markdown.
- Explain where GitHub looks for a README and how it displays it.
- Structure a README with a description, setup, and usage section.
- Write exact setup steps: required Java version, build command, run command.
- Add a short example of output so a reader can check that it worked.
- Test a README by following it exactly, as a stranger would.
Written Explanation
Markdown in ten minutes
A Markdown file is plain text, usually ending in .md. You write marks next to your text; a renderer (GitHub, an editor preview) shows the formatted result. These are the ones you need:
| You write | You get |
|---|---|
# Title | A level-one heading (largest). ## is level two, ### level three, up to six # |
| A blank line between blocks | A new paragraph |
- item on each line | A bulleted list (* and + also work) |
1. step on each line | A numbered list |
`code` | Inline code in a fixed-width font |
**bold** | bold |
*italic* | italic |
[text](https://example.com) | A clickable link |
For several lines of code, use a fenced code block: put three backticks on a line before and a line after. Writing a language name after the opening backticks (for example bash or java) is widely supported to enable colouring, but treat it as optional:
```bash
javac Main.java
java Main
```Two things trip beginners up. First, in Markdown a single line break is not a new paragraph: leave a blank line. Second, headings and lists need their mark at the very start of the line (a # must be followed by a space, #Title may not render as a heading in every renderer).
Since this is plain text, it works well with what you already know: Git can show a clear diff of a Markdown file, and a reviewer can comment on a README line in a PR exactly as on code.
Where the README lives
GitHub looks for a file named README.md in three places: the hidden .github folder, the repository's root folder, and a docs folder, using the first it finds in that order. Put yours in the root. GitHub shows it automatically on the repository's main page and renders the Markdown, builds an outline from the headings, and adjusts relative links to the branch being viewed. (A public repository named exactly like your username can use its README as your profile page, a handy portfolio trick.)
What a README must say
GitHub's own guidance says a README should tell visitors what the project does and why it is useful, how to get started, and where to get help or who maintains it. For this course, three sections are the minimum:
- Title and description. One heading, then one to three sentences: what is it, who is it for?
- Setup. How to get the project running from nothing. This is the section most often missing, and the most valuable.
- Usage. How to run it and what to expect, with a small example of output.
Writing setup steps that actually work
"Setup" means a stranger with a clean computer can follow it step by step. Be exact:
- The required Java version, such as "Java 21 or newer". Do not make people guess.
- How to get the code:
git clone <url>andcdinto the folder. - The build command, exactly as you type it, such as
javac Main.java. - The run command, such as
java Main. - What success looks like: the first line the program prints.
Put every command in a code block so it can be copied. Mention the folder each command runs in. If something has to be installed (a JDK), say so and link to where to get it.
The "stranger test"
You cannot judge your own README, because you already know everything it leaves out. The cure is a test: ask someone who has not seen the project to follow only the README. Watch where they hesitate. Every question they ask is a missing line. Typical gaps are the Java version, the build command, and the folder to run it from. Fix the README, not the person.
Examples
Example 1: a minimal README (simple)
# Bank Accounts
Console app for deposits and withdrawals.
## Setup
Requires Java 21.
## Usage
Run `java Main`.Rendered, this gives a large title, a short description, and two second-level headings. It is a start: it says what and how, but not how to build. The next example fixes that.
Example 2: add a code block and a result (practical)
# Bank Accounts
Console app for deposits and withdrawals.
## Setup
1. Install Java 21 or newer.
2. Clone the project and enter its folder:
```bash
git clone https://github.com/you/bank-accounts.git
cd bank-accounts
```
3. Compile:
```bash
javac Main.java
```
## Usage
```bash
java Main
```
Expected output:
```text
Bank accounts ready
```I compiled and ran a tiny Main.java that prints one line with exactly these two commands in a scratch folder (JDK 21), and it printed Bank accounts ready, matching the "Expected output" block. A README is only as good as this check: run your own commands.
Example 3: a realistic README for a portfolio (realistic)
# Bank Accounts
A console application that manages bank accounts: create an account,
deposit, withdraw, and show the balance. Built while learning Java.
## Requirements
- Java 21 or newer (check with `java -version`)
- Git
## Setup
1. Clone the repository: `git clone https://github.com/you/bank-accounts.git`
2. Go into the folder: `cd bank-accounts`
3. Compile from the project folder: `javac -d out src/*.java`
## Usage
Run from the project folder:
`java -cp out Main`
You should see a menu. Type the number of an option and press Enter.
## Project layout
- `src/` : the Java source files
- `out/` : compiled classes (not committed, see `.gitignore`)
## Status
Learning project. Planned next: automated tests.Notice what this README does well. It lists requirements first, gives each command in one place, says which folder to run it from, and explains why out/ is not committed, echoing the .gitignore lesson. A reviewer can see the project's shape in a few seconds. (The javac -d out src/*.java form assumes a Unix-like shell for the *; other shells or an IDE may need a different way to list the files, so adapt the command to your own setup and then test it.)
Backend Insight
Real backend projects add to this same skeleton: environment variables the service needs, how to start a local database, how to run the tests, and where the API is documented. Teams rely on the README as the entry point for new members, so a new colleague can set up a working environment on their first day without interrupting anyone.
Because the README lives in the repository, it follows the same workflow as code: a change to setup steps goes through a pull request and can be reviewed. When the build command changes, the README must change in the same PR, or it becomes a lie. Outdated setup instructions are among the most frustrating things in a codebase, and a good habit is to update the README whenever the way to run the project changes.
For you, the README is also a portfolio piece. People who evaluate candidates often open a repository, read the README, and try the commands. A working README shows care, communication, and that you finish things.
Common Mistakes
Mistake 1: No setup steps
- Incorrect: a README that says only "Bank app, written in Java".
- Correct: add the Java version, the clone, build, and run commands, and an example result.
Mistake 2: Commands that do not work
You wrote the build command from memory and it has a typo, or it assumes a folder you were standing in. Copy the commands from your terminal after they ran successfully.
Mistake 3: Forgetting the blank line
Two lines written one after the other are one paragraph; a list needs a blank line before it in many renderers. Preview before committing.
Mistake 4: Putting secrets or personal paths in the README
Never include tokens, passwords, or paths such as your own user folder. Use placeholders.
Mistake 5: Writing for yourself
"Run it like last time" means nothing to a stranger. Write for someone who has never seen the project, and run the stranger test.
Exercises
Level A: Foundation
A1. Write the Markdown for: a level-one heading "Library", a paragraph, a level-two heading "Setup", and a bullet list of two items.
Show solution A1
A1.
# Library
A small program that records books.
## Setup
- Install Java 21
- Compile with `javac Main.java`A2. What do these produce: **Note**, *Note*, `javac Main.java`?
Show solution A2
A2. **Note** gives bold text, *Note* gives italic text, and `javac Main.java` gives inline code in a fixed-width font.
A3. Where should README.md be placed so GitHub shows it on the repository's main page, and why that location?
Show solution A3
A3. In the repository's root folder. GitHub looks in .github, the root, and docs, in that order, and the root is the usual, most visible choice; GitHub displays it on the repository page.
Level B: Application
B1. Rewrite this into a proper Setup section with a code block: "to run it you need java and then compile Main.java and then run Main".
Show solution B1
B1.
## Setup
1. Install Java 21 or newer.
2. Compile:
```bash
javac Main.java
```
3. Run:
```bash
java Main
```B2. List the five things a setup section should contain so that a stranger can run a Java console project.
Show solution B2
B2. The required Java version; how to get the code (clone and enter the folder); the build command; the run command; what success looks like (expected output).
B3. This README line is broken: #Usage followed by java Main on the next line, with no blank line and no code block. Say what could go wrong and fix it.
Show solution B3
B3. The heading may not render as a heading because there is no space after #, and the command may merge into a paragraph. Fix:
## Usage
```bash
java Main
```Level C: Challenge
C1. Write a complete README (about 15 lines) for a project of yours, with title, description, setup, usage, and one expected output block. Then run each command yourself, in a fresh folder, and fix what fails.
Show solution C1
C1. Many answers are correct. Check: Java version is named; every command is in a code block; commands are in the order setup, build, run; the expected output matches what the program printed when you ran it; and the folder is stated. Fixing failures (for example a missing cd) is the point.
C2. A reviewer on your PR writes "I cloned it and javac Main.java says it cannot find the file." Give three possible causes in the README, and how you would change it.
Show solution C2
C2. Likely causes: the README does not tell the reader to cd into the project folder, the file lives in a subfolder such as src/ that the command does not mention, or the file name or case differs from the README. Change the README to state the folder, give the exact path-aware command, and run it from a fresh clone.
Mini Challenge
Write the README for a project you want to publish in the module lab. It needs a title, a description of two sentences or fewer, a Requirements line with the Java version, a Setup section with clone, build, and run commands in code blocks, and an expected output block.
Then run the stranger test: give the README, and nothing else, to a peer. Note every place they hesitate or ask a question, and fix the README. Commit it through a branch and a pull request.
Check your work: the README renders correctly on GitHub, each command works exactly as written, and the peer reached the expected output without asking you anything.
Summary & Next Lesson
Key takeaways
- Markdown is plain text with simple marks:
#headings,-lists, backticks for code, and fenced blocks for several lines. - GitHub shows a root-level
README.mdon the repository's main page. - A README states what the project is, how to set it up, and how to use it.
- Setup steps are exact: Java version, clone, build, and run commands, plus the expected output.
- Run your own commands, and test the README on a stranger.
Next lesson
You now have all the pieces: remotes, authentication, pull requests, and a README. The next lesson, "Demo: publishing a project and reviewing a pull request", puts them together in one walk-through, including a planned mistake.
Self-check
- Which Markdown produces a level-one heading?
- How do you show several lines of code in Markdown?
- Which README section lets someone else run your project?
- Name two things the setup section must state exactly.
- What is the stranger test?
Show answers
# Title.- In a fenced code block: three backticks on the line before and after the code.
- Setup.
- Any two of: the Java version, the build command, the run command, the folder to run from.
- Giving only your README to someone new, and fixing every place they get stuck.
References
- GitHub Docs, Basic writing and formatting syntax. Supports: headings with one to six
#, lists, inline code, fenced code blocks, links, bold and italic. - GitHub Docs, About READMEs. Supports: what a README should include, where GitHub looks (
.github, root,docs), automatic display, outline, and the profile README. - Not verified from a fetched page: the advice that a blank line is needed before lists and between paragraphs, that
#Titlewithout a space may not render, and the optional language tag on fenced blocks. These reflect common Markdown behaviour and vary slightly between renderers, so preview your file. Thejava/javaccommands in Example 2 were run locally with JDK 21; the commands in Example 3 were also run locally (a one-file project undersrc/, JDK 21, Git Bash) and printed the same line.
Practice
Apply this lesson with the module's lab, exercises and quiz.
Marking a lesson complete is optional and you can undo it any time. Your progress stays in this browser.