Docs are the surface you build. Community is the relationship you tend. The repository page is neither, and it is frequently the first thing a developer sees — arriving from a search result, a dependency list, a colleague’s link, or a model’s citation. It is a marketing artifact that most teams have never treated as one.

The README is a landing page you did not design

It gets more qualified traffic than your homepage and usually less thought. Apply the same discipline: the first screenful decides.

  • One sentence saying what this is, in the reader’s words, before any badge. A reader who has to scroll past a wall of shields to learn what the project does has already been told what you optimise for.
  • Install and first success, immediately. The command, then the smallest snippet that does something real. If the shortest path to a working result is below the fold, move it.
  • A picture of the thing working — a GIF, a screenshot, a terminal cast. For anything with visible output this is the single highest-return element in the file.
  • The scope, stated honestly. What it does not do, what is experimental, what platform it assumes. Same rule as everywhere else: naming the limits early costs you the wrong users and keeps the right ones.
  • Where to go next — docs, discussions, the hosted version if there is one. The README’s job is to hand off, not to become the documentation.

Badges deserve a specific warning. A row of twelve is noise; two or three that a reader would actually act on (build status, current version, license) are furniture. The rest are a signal about the maintainer, not the project.

Getting found is a separate job from being good

GitHub is a search engine that most projects never optimise for and that models increasingly read. Three fields carry nearly all of the weight, and all three are one edit away:

  • The repo description — the line under the name is what appears in search results, in social cards and in most citations. Write it as a search result, not as a slogan.
  • Topics — the tag list is the primary facet for GitHub’s own discovery and for the “awesome” lists and directories that scrape it. Use the terms people search, including the ones you find slightly beneath you.
  • The repo name. A cute name that contains none of the words describing the job costs you discovery permanently, and it is the one decision here you cannot cheaply revise later.

Stars are a signal you cannot spend

Stars correlate with attention, not adoption, and every developer knows it. They are worth having and worth almost nothing as a target: download counts, dependent repositories and active contributors all say more about whether the thing is used.

That said, asking is legitimate. A star prompt in the docs nav or a persistent site element is normal practice and costs little goodwill when the project is genuinely useful. What reads badly is the ask arriving before the value — a modal on first visit, a prompt in the installer, a growth loop where a working tool should be. And if you publish the number, publish the graph: a star-history curve is checkable, a round number in a headline is not.

Releases are a publishing channel

Most teams write release notes as a changelog obligation and then separately wonder how to stay present between launches. They are the same problem. A release note that says what changed, why, and what a user has to do about it is content with a built-in audience — watchers get it delivered, aggregators pick it up, and it is the artifact that proves the project is alive to anyone evaluating it. Tag properly, write in prose rather than commit subjects, and link the migration path when there is one.

The issue tracker is a page your buyer reads

Before a team adopts a dependency, someone opens the issues and sorts by recent. They are reading for one thing: what happens when I have a problem. What they find is a live measure of the project’s health that no marketing page can override — response times, the tone of maintainer replies, how old the oldest open bug is, whether “stale bot closed this” is the most common last comment.

Treat it accordingly. Templates that ask for what you actually need, labels a stranger can navigate, and a visible answer on the ones that matter. A tracker with 900 open issues and no triage says something specific about operational maturity, and it says it to exactly the person deciding whether to depend on you.

License and governance are positioning

For anything open source, the license is a positioning statement with legal force, and developers read it as one. So is the governance around it: whether a CLA is required, who can merge, whether the roadmap is public, and — increasingly — what your policy is on AI-assisted contributions. Publishing those answers before someone has to ask for them removes the single largest source of hesitation for a team considering a real dependency. Leaving them ambiguous does not avoid the question; it just moves it into a private thread you never see.