
Mission 2 of 6
Build a repo people trust in ten seconds.
A visitor from Hacker News gives your repo about ten seconds to look like a real project. You'll build the first screen and the files behind it, from a template you can reuse.
What you'll do
Put the one line, the demo GIF, a one-command install and three examples in the order visitors read them.
Keep four useful badges, then add CONTRIBUTING.md and issue templates that ask every bug report for a version and a reproduction.
Write a CHANGELOG, follow simple version rules and publish a tagged v0.1.0 release.
- A terminal GIF you can re-render with one command
- A ten second checklist to run before you share any link
- The repo from pick a project people will star, with some working code in it. Even a rough first version is fine
ghlogged in, and VHS installed for the GIF (step 2 links the install mission)- If you don't have CI yet, that's fine for now; step 5 tells you where to get it
Your progress0/5
The README, in the order people read it
Write the first screen so a stranger knows what it does, sees it work and can install it without scrolling.
A visitor from Hacker News gives your repo about ten seconds. They aren't reading code. They're deciding whether it's a real project or a weekend dump, and the first screen is what they decide on.
People read a README top to bottom and stop the moment they've decided. So the order matters more than the content.
The order, and why
Each slot comes with the reason for it:
- Name and one line. The description from the last mission. What it does, for whom, no adjectives.
- The GIF. Before any text. The visitor sees the tool work before they've read a sentence. Step 2 makes it.
- Badges. One row, under the GIF. Four at most. Step 3.
- Install, one command. If it takes more than one line, the first line is the one-liner and the rest goes in a collapsed section or a docs page.
- Three examples. The simplest use, the most common real use, and one that shows the thing competitors can't do. Each is a command with one line of context above it. Three, not ten; ten means nobody reads any.
- Why not the obvious alternative. One short paragraph. Every visitor is thinking 'why wouldn't I just use jq'. Answer it before they ask or they leave to go and use jq.
- Roadmap. Three to five checkboxes. It shows the project is alive and gives visitors a reason to star (to come back for the next item). Link to Discussions for votes.
- Contributing and licence. One line each, linking to the files.
The template
Copy the template below to
README.mdand replace every line that mentions jdx with your project. It's filled in for the worked example from the last mission.README.md# jdx Diff two JSON files, ignoring key order and the noise you don't care about.  [](https://github.com/OWNER/jdx/actions/workflows/ci.yml) [](https://pypi.org/project/jdx/) [](https://pypi.org/project/jdx/) [](LICENSE) ## Install ```bash pip install jdx ``` ## Use Diff two files, ignoring key order: ```bash jdx old.json new.json ``` Ignore fields that always change: ```bash jdx old.json new.json --ignore updated_at --ignore "*.etag" ``` Fail a CI step when two API responses differ: ```bash curl -s https://api.example.com/v1/config > live.json jdx expected.json live.json --exit-code ``` ## Why not jq or diff? `diff` sees key order and whitespace. `jq -S` sorts keys but can't ignore fields or arrays-as-sets. jdx does both and prints a diff a human can read. ## Roadmap - [x] Ignore paths with globs - [ ] YAML input - [ ] Treat arrays as sets with `--unordered-arrays` Vote on the next one in [Discussions](https://github.com/OWNER/jdx/discussions). ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md). Good first issues are [labelled](https://github.com/OWNER/jdx/labels/good%20first%20issue). ## Licence MIT.
What's deliberately missing
There's no 'Features' bullet list (the examples are the features), no 'Motivation' essay (that's a blog post) and no table of contents (it's one screen).
There's no architecture section either, because that goes in docs/ or CONTRIBUTING. And there's nothing about how much you learned. Your learning is real but it's not what the visitor came for.
Make the examples real
The examples are the part to spend time on. Run each one for real and paste the actual command.
If an example needs a file, commit a tiny one under examples/ so the reader can run it in thirty seconds. A README whose examples work on first copy-paste is rarer than you'd think and people notice.
If it breaksMy install isn't one command yet + 1 more
My install isn't one command yet
pip install NAME or npm i -g NAME) and put the current git clone route in a collapsed <details> block titled 'Install from source'. The next mission makes the one-liner true.