Template README

README.md: the first thing anyone reads about your project

The README.md is the first artifact any developer opens when they land on a repository. It is the front door of the project: a five-paragraph pitch that decides whether a stranger will install your library, contribute to your codebase or move on. A weak README costs more than a weak landing page — it actively reduces adoption of work that may be otherwise excellent.

The classical sections are well documented (see github.com/matiassingers/awesome-readme and the Standard Readme spec by jbenet): Title with an optional logo, Badges (build status, npm version, license), Description in one or two sentences, Installation, Usage with a runnable code example, API or Configuration, Examples, Contributing, License, Acknowledgments. Tools that generate READMEs include readme.so (drag-and-drop blocks) and Make a README by Daniel Beck.

README-driven development

In 2010 Tom Preston-Werner, GitHub co-founder, published the famous post "Readme Driven Development". The premise: write the README first, design the public API around it. The README forces you to argue for the project before you have built anything — if you cannot make a compelling case in a page, the project probably should not exist yet. RDD is closely related to documentation-first design and works particularly well for libraries and CLIs.

Badges, GIFs and GitHub-native features

Badges: shields.io is the default — build status, npm version, downloads, license, code coverage. forthebadge.com is the humor variant. For visual demos, use a GIF or screenshot near the top — for CLIs, asciinema records terminal sessions and embeds beautifully. GitHub itself supports rich features inside Markdown: emoji shortcodes (:rocket:), task lists (- [x]), tables, syntax highlighting and — since 2022 — native Mermaid diagrams rendered straight from fenced code blocks.

Multilingual READMEs, profile READMEs and anti-patterns

The community convention for multilingual projects: keep README.md in English (the default) and add README.pt-BR.md, README.zh-CN.md next to it; link to translations at the very top. The profile README is a special trick: create a repository whose name equals your GitHub username, add a README, and it pins on your profile page. Anti-patterns to avoid: ten paragraphs of installation before showing what the tool actually does; no example; outdated screenshots; missing license. For full documentation sites, hand off to Docusaurus, VitePress or Docsify and link from the README; keep a CONTRIBUTING.md as a separate file.

FAQ

Markdown (.md) or reStructuredText (.rst)? Markdown dominates GitHub and the open source ecosystem. RST is still standard in the Python world (Sphinx documentation), but for the project entry point on GitHub you want .md.

Is the README mandatory on GitHub? Technically no — the platform does not enforce one. In practice it is critical UX: GitHub renders it on the repository home page, and search and AI tools index it heavily.

How do you handle multilingual READMEs? Convention: a row of links at the very top, one per language, each pointing to the corresponding README.<locale>.md. Some projects (Hugo, Zod, Vercel AI SDK) are great references for tasteful execution.

What goes in CONTRIBUTING.md vs README? README is the visitor's pitch and quick-start. CONTRIBUTING is the contributor's manual: branch naming, commit style, test workflow, code of conduct link. Keep them separate so a casual user is not buried in setup detail.