Writing a README that people read

A README is the front door of a project. Judges, teachers and strangers on the internet decide in about a minute whether your work is worth their attention, and that minute is spent on your first screen of text.

Start with one sentence that says what the project does and for whom: "FitForm League is a free web app that uses a camera and on-device AI to count exercise repetitions for secondary school students." Avoid adjectives such as revolutionary; let the verbs carry the meaning. Follow with a short list of what actually works today, separated clearly from what is planned, because a reader who discovers that a promised feature does not exist stops trusting the rest of the page.

Then make the project easy to try. Give the live link first, then the three commands that run it locally. Add one screenshot, because a picture answers questions that a paragraph cannot. Explain the architecture in five lines, not fifty: which part runs in the browser, which part runs on the server, and where the data is stored. Finish with the numbers you can defend, the licence, and a way to contact you. Write it in English, and keep it honest: a modest claim that holds up is worth more than a bold one that does not.