Open source project website content checklist

An open source project site has to take a stranger from curiosity to a working install in minutes, and show that the project is still maintained. Most delays come from licence details, contributor guidance and maintainers who answer slowly.

8 pages43 requests23 requiredAnswered by the lead maintainer

Where to start

  1. Brand and licence. The licence, copyright line and domain owner are fixed facts that other people may need to confirm.
  2. Getting started. The install and quickstart must be tested on a clean machine, which takes the maintainer's time.
  3. Documentation. Deciding whether to host or link the docs changes the navigation and the build for the whole site.
  4. Maintainers and governance. It depends on several volunteers replying, so the questions should go out early.
  5. Home. The hero sample and headline are easy to settle once install and docs are known.

The checklist

Home

A developer decides in under a minute whether to try the project, so the home page needs a code sample that works and proof of life, and it goes wrong when it reads like a press release.

  • Project name and one-line description Short text, requiredThe name as written in the repository, including capitals, then one line on what it does. For example: 'Fastlane Router, a typed URL router for small Node apps.'
  • Hero code sample Long text, requiredThe shortest snippet, ideally under 12 lines, that shows the project doing something useful. Test it on a clean machine, because a broken sample on the home page costs you adopters.
  • Main button Single choice, requiredThe first thing a new visitor should do. Most projects pick the docs, but a downloadable tool may want an install button instead.Get startedRead the docsView on GitHubDownloadTry it in the browser
  • Status badges to show Multiple choiceTick the live badges you want near the top. Only pick ones that are green and kept up to date by CI.Build statusLatest releaseLicenceDownloads per weekTest coverageChat members
  • Stars, downloads and users Short textReal figures from GitHub or the package registry with the date. Companies using the project in production are worth naming if they agree.
  • Logo or mascot as a social image Image uploadA 1200 by 630 pixel image for link previews on Mastodon, X and chat apps, if one exists. Otherwise the designer will make one from the logo.

Getting started

Most visitors never get past install, so this page must work on a clean machine, and it fails when the steps were written for the maintainer's own setup.

  • Install commands Long text, requiredEvery supported install route with the exact command, such as npm, pip, cargo, Homebrew or Docker. Paste from a terminal rather than retyping.
  • Supported platforms and versions Long text, requiredOperating systems, language runtimes and major versions you test against. Say what happens on older versions, so people do not file bugs for them.
  • Quickstart walkthrough Long text, requiredFive steps or fewer from install to a working first result, with the expected output after each step. Have someone who has never used the project try it.
  • Example repository LinkA link to a small repository, template or playground that users can clone and run. Check it still builds against the latest release.
  • Prerequisites to name Long textTools or accounts a user needs before step one, such as a compiler, a database or an API key. List only the real requirements.

Documentation

Docs are the main product of many open source sites, and this page has to decide whether the site hosts them or points to them.

  • Documentation tool Single choice, requiredThe system that builds the docs today. The designer either themes it to match the main site or links out to it.DocusaurusMkDocsSphinxGitBookMarkdown in the repository onlyNot built yet
  • Documentation address LinkThe live docs link. If docs are in the repository, give the folder path and the branch that holds the current version.
  • Docs for older versions Yes or no, requiredSay whether people can read docs for earlier major versions. If yes, the site needs a version switcher and a notice on old pages.
  • Gaps users report Long textThe three pages people most often ask for that do not exist. The designer can leave room in the navigation for them.
  • API reference source Single choiceWhere the reference comes from, since generated and handwritten references need different treatment.Generated from code commentsHandwrittenOpenAPI or schema fileNot available

Community and contributing

Contributors judge whether it is worth their evening by how friendly and responsive the project looks, so this page has to be specific about how to help.

  • Where discussion happens Multiple choice, requiredTick each place where users get answers. The site lists them with a join link and a note on typical reply speed.GitHub DiscussionsDiscordSlackMatrixForumMailing listStack Overflow tag
  • Contribution guide Link, requiredThe CONTRIBUTING file or docs page. If it is out of date, name who will update it before launch.
  • Label for beginner issues Short textThe exact label in the issue tracker, such as 'good first issue'. The site links to a filtered list of those issues.
  • Code of conduct File upload, requiredThe document contributors agree to. Many projects adopt the Contributor Covenant, so say which version and whether it has been edited.
  • Who receives conduct reports Short text, requiredAn email or role that reports go to, and who else can see it. Reporters want to know their message will not reach the person they are reporting.
  • Show contributor avatars Yes or noSay whether the site may pull contributor names and avatars from GitHub into a wall. Some contributors prefer to stay off public pages.

Maintainers and governance

Companies adopting the project ask who runs it and how decisions are made, and this page is often blank because the answers have never been written down.

  • Maintainer names and roles Long text, requiredEach active maintainer with their handle, role and area of the code. Include an employer only if they want it shown.
  • Maintainer photos Image uploadOptional portraits, square, at least 600 pixels. Skip anyone who prefers to use an avatar or stay anonymous.
  • Governance model Single choice, requiredPick the closest description of how decisions get made. If it is a de facto arrangement, say that plainly.Single maintainerSmall core teamSteering committeeHosted by a foundationCompany-led
  • How decisions are made Long textDescribe how a change or a breaking release gets agreed, and who has the final say. A link to a governance file is enough if one exists.
  • Security contact and policy Short text, requiredThe private address or advisory page for reporting vulnerabilities. Security teams look for it before approving a dependency.

Sponsors and funding

Funding keeps small projects alive, and the page works only when it names who pays, what the money does and what the sponsors agreed to.

  • Funding channels Multiple choice, requiredTick where donations or sponsorships go today. The site gets one button per channel, so only tick active ones.GitHub SponsorsOpen CollectivePatreonKo-fiTideliftCompany donationsNo funding yet
  • Sponsor logos File uploadSVG or PNG logos of current sponsors, as supplied by them. Do not grab logos from search results, because they may be outdated.
  • Permission to show sponsor logos Yes or no, requiredConfirm each sponsor in the list has agreed to appear. Check any sponsorship terms that set logo size or placement rules.
  • Where the money goes Long textA short breakdown such as maintainer time, hosting and bounties, with amounts if you publish them. Sponsors ask for it, and a plain list builds trust.

Releases

A clear release page tells users whether the project is moving and which version to choose, and it breaks when the numbers on the site lag the repository.

  • Latest stable version Short text, requiredThe number of the current stable release, such as 3.2.0, and its date. Say whether the site should read it from the registry or from a fixed field.
  • Release notes link or file Link, requiredThe address of the changelog or releases page. If notes are written per release, name where the designer can pull them from.
  • Release schedule Short textHow often you ship, for example 'a minor release every six weeks'. Leave blank if releases are irregular and say so.
  • Long-term support policy Long textWhich older versions still get fixes and until when. Companies check this before committing to a major version.
  • Public roadmap LinkA link to a milestone board or roadmap file. Only link one the maintainers actually keep current.

Brand and licence

Adopters read the licence before the docs, and the project name and logo often have no clear owner, so this page settles both.

  • Software licence Single choice, requiredThe licence in the repository today. The site shows its name and links to the full text, so it must match the LICENSE file exactly.MITApache 2.0GPL v3BSD 3-ClauseMPL 2.0Another licence
  • Copyright holder line Short text, requiredThe name in the footer, as it appears in the licence file, such as 'The Fastlane Router contributors'. Check it with whoever holds the copyright.
  • Logo files File upload, requiredVector logo (SVG) in full colour and one colour, plus a version for dark backgrounds. Open source logos need to work small, in a README or a conference slide.
  • Brand colours ColourThe primary colour and any accent as hex codes. If the logo was drawn by a contributor, ask them for the original file and palette.
  • Brand fonts FontTypeface used in the logo or docs theme. Prefer open fonts that match the project's licence ethos, and say if the logo is outlined.
  • Logo and name usage rules Long textWhat others may do with the name and logo, for example talks, forks or products. Say who owns the trademark, or that nobody does yet.
  • Domain and hosting owner Short text, requiredThe person or organisation that holds the domain and DNS login. If it is one maintainer's personal account, flag it now.

What clients get stuck on

A quickstart that only works on the maintainer's laptop

Ask someone outside the project to run the steps on a clean machine and record where they stall. The fixes belong in the docs before the site goes live, not after the first angry issue.

Governance that exists only in habit

Small projects rarely have written rules. Ask the maintainers how they would resolve a disagreement and write that down as a draft, then have them confirm it, rather than inventing a committee.

Sponsor logos without permission

Sponsors pay on a platform and never say yes to a logo. Ask each one by email or through the platform, and keep the replies, before their marks go on a public page.

A volunteer maintainer who is slow to reply

Maintainers have day jobs. Send one batched list of questions with defaults they can approve with a single word, and book a short call rather than waiting on email threads.

A logo nobody has the source for

Many project logos come from a contributor's old drawing. Ask for the original vector file early, and if it is lost, plan to redraw it and get the owner to agree to the new version.

Copy the checklist

Plain Markdown you can paste into a doc or an email.

# Open source project website content checklist

## Home
- [ ] Project name and one-line description (Short text, required)
- [ ] Hero code sample (Long text, required)
- [ ] Main button (Single choice, required)
- [ ] Status badges to show (Multiple choice)
- [ ] Stars, downloads and users (Short text)
- [ ] Logo or mascot as a social image (Image upload)

## Getting started
- [ ] Install commands (Long text, required)
- [ ] Supported platforms and versions (Long text, required)
- [ ] Quickstart walkthrough (Long text, required)
- [ ] Example repository (Link)
- [ ] Prerequisites to name (Long text)

## Documentation
- [ ] Documentation tool (Single choice, required)
- [ ] Documentation address (Link)
- [ ] Docs for older versions (Yes or no, required)
- [ ] Gaps users report (Long text)
- [ ] API reference source (Single choice)

## Community and contributing
- [ ] Where discussion happens (Multiple choice, required)
- [ ] Contribution guide (Link, required)
- [ ] Label for beginner issues (Short text)
- [ ] Code of conduct (File upload, required)
- [ ] Who receives conduct reports (Short text, required)
- [ ] Show contributor avatars (Yes or no)

## Maintainers and governance
- [ ] Maintainer names and roles (Long text, required)
- [ ] Maintainer photos (Image upload)
- [ ] Governance model (Single choice, required)
- [ ] How decisions are made (Long text)
- [ ] Security contact and policy (Short text, required)

## Sponsors and funding
- [ ] Funding channels (Multiple choice, required)
- [ ] Sponsor logos (File upload)
- [ ] Permission to show sponsor logos (Yes or no, required)
- [ ] Where the money goes (Long text)

## Releases
- [ ] Latest stable version (Short text, required)
- [ ] Release notes link or file (Link, required)
- [ ] Release schedule (Short text)
- [ ] Long-term support policy (Long text)
- [ ] Public roadmap (Link)

## Brand and licence
- [ ] Software licence (Single choice, required)
- [ ] Copyright holder line (Short text, required)
- [ ] Logo files (File upload, required)
- [ ] Brand colours (Colour)
- [ ] Brand fonts (Font)
- [ ] Logo and name usage rules (Long text)
- [ ] Domain and hosting owner (Short text, required)

Questions about this checklist

Should an open source project use a separate site or just the GitHub README?

A README works for a small library. Once you want search ranking, versioned docs, sponsor placement or a place for non-developers to land, a site pays off. Keep the README short and link to the site from it.

Who should own the domain for a community project?

Ideally an organisation or a shared account, not one maintainer's personal login. If a person holds it, record a second admin, because a lost domain breaks every link in every package page.

Is it fine to show download counts and GitHub stars on the site?

Yes, if they are real and dated or pulled live. Stale numbers harm trust, so either fetch them automatically or leave them off. Never round up, since developers check the registry.