SEO for an open source project: the docs, GitHub, and the comparison

Focus on three assets: the docs site, the GitHub repository, and the package registry page. Each serves a different query and a different intent.

• Docs earn task, comparison and error searches. They are what assistants cite.
• GitHub and package pages rank on the tool’s name. Stars and recent commits are trust.
• A clear comparison to alternatives converts evaluators who search “X vs Y” and “X alternatives”.

Your goal: the docs page answers the job in one screen, then links to install, examples and production guidance. The repo and package pages point to those docs, not to a wall of badges.

Open with one plain sentence that names the category and the job. Assistants and skimmers quote it and decide in seconds whether to stay.

1. 1

   Pick a stable category word

   Use the words your audience recognises today. If labels churn, anchor on the job, for example “Generate TypeScript types from JSON Schemas” not a fad term.

2. 2

   Write it once, reuse it

   Put the sentence at the top of /docs, /docs/getting-started and README.md. Keep the same project name and description everywhere.

3. 3

   Then add the who and the how

   A second sentence can say “For Node and Python, works offline, MIT licensed.” Keep it short.

Example before: “Blazing fast, powerful toolkit.” After: “A CLI and library to diff large JSON files and stream changes to Postgres.” That after is quotable and searchable.

Developers search by task, by comparison, by alternative and by error message. Write one page per task and per error you handle.

• Getting started: /docs/getting-started with install and a 60‑second success.
• Tasks: /docs/how-to/connect-to-mysql, /docs/how-to/stream-logs-to-s3.
• Errors: /docs/errors/your-computer-is-running-low-on-resources if your tool mitigates it or logs it.
• Config and limits: /docs/limits and /docs/configuration with defaults and code blocks.
• Versioning: one canonical per version, and an obvious version switcher.

1. 1

   Answer first

   Start pages with the command or code that solves the task, then context. Keep headings specific: “Rotate tokens with cron” beats “Security”.

2. 2

   Link onward

   Every task page links to examples, API reference and a related task. Use descriptive anchor text, for example “see the Kafka sink example”.

3. 3

   Name things consistently

   Use the same integration names across pages, for example “PostgreSQL” not “Postgres” in one place and “PG” in another.

Docs are read by developers and by assistants as of 2026. Keep the answers in the HTML with headings, lists and code blocks that can be quoted directly.

Your repo will rank on the project name. Treat the README as a landing page that routes traffic to the right docs page in one click.

• First two lines: the same one‑sentence description and a link to /docs/getting-started.
• Installation snippet for the main package manager, then a minimal example.
• Badges are fine, but keep them under the example. Avoid eight badges before any code.
• Link to /docs/comparison at the top for evaluators. Link to /docs/hosted for the managed option.

Keep stars, recent commits and releases visible. They are a trust signal. Pin examples and a short issue template that points people to /docs/errors/ for known problems and fixes.

npm, PyPI, crates.io and Docker Hub pages rank on the package name. They must confirm fit and send users to the docs fast.

1. 1

   Copy the first sentence

   Use the same one‑line description in package metadata. People compare packages in lists, so consistency helps.

2. 2

   Add links to tasks

   Point to /docs/getting-started and one or two top how‑to pages, for example “stream-logs-to-s3” and “parse-nginx-logs”.

3. 3

   Show a 30‑second example

   A one‑file example is enough. Keep it aligned with the getting started page so users land and complete.

For Docker images, keep tags tidy and README sections short. Link out to version‑specific docs when needed, with the version number in the link text.

Evaluators search “X vs Y” and “X alternatives”. Being there is the difference between a star and a pilot. Treat these pages as product content, not blog posts.

Keep the title under about 60 characters so it fits. Example: “Stargazer vs ELK: log diffing for noisy clusters”. Use the product names in headings and in a single comparison table assistants can lift.

Many users will want a managed option. They should find it in the docs, not as a takeover banner on the repo. Keep trust in the project first.

• Add /docs/hosted with what the service runs, SLAs, limits and the price. Link to it from install and production guides.
• On task pages, add a note near production steps: “On Hosted, this is preconfigured” with a link, never a modal.
• Keep the project domain as the docs domain. Use a top link in the navbar for “Hosted” rather than swapping the home page.

A fixed page looks like: /docs/hosted explains the architecture, supported versions, regions and a path to migrate from self‑hosted with a checklist. That is genuine help and converts without noise.

Search‑backed assistants retrieve pages and cite the ones that answer directly with clear structure. There is no submission form. You have to qualify by writing pages that can be quoted and by allowing their crawlers.

• Allow answering and search crawlers in robots.txt, for example Googlebot, Bingbot, OAI-SearchBot, Claude-SearchBot and PerplexityBot as of 2026.
• Publish an llms.txt at the docs root that names your project, the docs sections and how to cite.
• Add a “What it is” page that assistants can use to summarise the tool and its limits and licence.
• Be on third‑party lists and comparisons assistants already cite, including directories and incumbent comparisons.

Measure GEO by asking assistants the questions your buyer asks and noting who is named. If you are never cited on “how to X in Y”, add that task page and link to it from the README and package page.

A dated changelog and an integrations index earn and convert long‑tail searches. They also reassure evaluators that the project lives and plays well with their stack.

• /changelog with dates and links to the docs sections that changed. One entry per release.
• /integrations with one page per system: “PostgreSQL”, “S3”, “Kafka”. Each page starts with one paragraph and a working example.
• Link integration pages from relevant task pages and from README sections. Keep names exactly as vendors write them to match searches.

A fixed integration page looks like /integrations/s3 with a minimal policy, IAM example and a link to /docs/how-to/stream-logs-to-s3. That answers the query and routes to the task.

Your links travel through GitHub, forums and chat. Make the preview clear and keep URLs stable so people trust and share them.

• Set Open Graph title and image on the docs home and top pages so previews make sense in Slack and X.
• Use short, stable slugs, for example /docs/errors/out-of-memory not a dated or numbered slug.
• Redirect old slugs with 301s when you rename pages. Do not silently break links from blog posts and answers.

You do not need an image per page. A single branded docs image and per‑section titles are fine. The point is clarity, not art direction.

Small projects start with a few authoritative links and mentions. Ship where developers read, then keep earning links by writing the pages that answers cite.

• Launch on Product Hunt, Hacker News and Indie Hackers for the first links. Point all posts to the docs home and /docs/getting-started.
• Answer Stack Overflow with working snippets and link to the exact task page. Never link the home page in an answer.
• Pitch maintainers of incumbents’ alternatives pages with your new comparison page where it fairly includes them.
• Add a CONTRIBUTING.md section on writing docs and comparisons. Offer “good first issue” tickets for missing task pages.

Contributors as writers is a force multiplier. Label issues like “Write /docs/how-to/parse-nginx-logs” with context and a draft. Review for naming and links, not voice flair.

Connect the docs domain to Search Console. Read the Performance report weekly. You are looking for the jobs and errors you appear for but do not yet win.

1. 1

   Find tasks you rank on page 2

   Sort by average position and filter positions 8 to 20. These are striking distance tasks. Tighten the answer and add internal links.

2. 2

   Spot zero‑click pages

   Look for impressions with no clicks. Fix titles, meta descriptions and first paragraphs so they say the job in the user’s words.

3. 3

   Patch cannibalisation

   If two pages rank for the same task, merge them and redirect the weaker one. Keep one URL per job.

Review the Links report for external domains that mention you. If they link to the repo, ask for a docs link where it fits. If they cite an old slug, ask for an update after you redirect.