Get Started
Open source that pays

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.

60 minBeginnerFree toolsStep 1 free

What you'll do

Write the README and record a GIF

Put the one line, the demo GIF, a one-command install and three examples in the order visitors read them.

Add badges and contributor files

Keep four useful badges, then add CONTRIBUTING.md and issue templates that ask every bug report for a version and a reproduction.

Tag your first release

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
Before you start
  • The repo from pick a project people will star, with some working code in it. Even a rough first version is fine
  • gh logged 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
01/05The README, in the order people read it0 done
STEP 01 of 05~15 min

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

  1. Copy the template below to README.md and 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.
    
    ![demo](docs/demo.gif)
    
    [![CI](https://github.com/OWNER/jdx/actions/workflows/ci.yml/badge.svg)](https://github.com/OWNER/jdx/actions/workflows/ci.yml)
    [![PyPI](https://img.shields.io/pypi/v/jdx)](https://pypi.org/project/jdx/)
    [![Python](https://img.shields.io/pypi/pyversions/jdx)](https://pypi.org/project/jdx/)
    [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](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.

Tip
Read your README on your phone. GitHub's mobile view is how a lot of Hacker News traffic arrives. If the one line and the GIF don't both fit on the first screen, shorten the one line.
Checkpoint
Your README has the one line, a placeholder for the GIF, a one-command install and three examples that you have run yourself and that work from a fresh clone. The GIF slot is empty for now, and that's what the next step fills.
If it breaksMy install isn't one command yet + 1 more
My install isn't one command yet
Then write the one it will be after the next mission (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.
I can't think of a 'why not X' paragraph
That's a warning sign from mission 1, not a writing problem. Ask yourself what you'd have used last month before this existed. That's X. If the honest answer is 'nothing, I'd have done it by hand', write that: 'Why not do it by hand? It takes 20 minutes and you'll miss one.'
Still stuck? Ask the community
Next mission · Open source that paysShip the first release: pip install in one command, published by a git tag
→