Developer tools website content checklist
A developer tool site has to get an engineer from the home page to a working install in minutes, with code that runs as written. The delays come from sample code nobody tested, benchmark claims and docs owned by another team.
Where to start
- Install and quickstart. Commands and steps need engineering time to test, and they decide whether the site works for a new user.
- Docs and examples. Docs belong to another team, and the integration with them shapes navigation and design.
- Home. The tagline and hero sample set the voice of the site, and a lead can give them in one meeting.
- Pricing and licence. Licence and limits need legal and product sign-off, which takes time.
- Security and legal. Disclosure contacts and telemetry statements need an engineer's input, so ask early.
The checklist
Home
An engineer decides within a few seconds whether the tool fits their stack, so the home page needs a plain description and code on the first screen.
- Tool name and tagline Short text, requiredThe name as written in the docs and the package registry, with a one-line tagline that names the language or platform. Example: 'A test runner for Rust workspaces.'
- Problem the tool solves Long text, requiredTwo or three sentences on the pain it removes, in the terms an engineer would use in a bug report. Skip slogans about productivity.
- Hero code sample Long text, requiredA snippet of under 15 lines that someone can paste and run on a clean machine. Say which version of the tool it was tested against.
- Primary action Single choice, requiredPick the first thing most visitors should do. The home page leads with it.Install the toolRead the docsTry it in the browserView on GitHubStart a free account
- Hero terminal or interface capture Image uploadA screenshot or a short GIF or MP4 of the tool running. Use a clean terminal with a legible theme, and crop out any private paths or tokens.
Product overview
Engineers compare tools by how they fit existing workflows, so the page has to state what the tool does and where it stops.
- Main capabilities Long text, requiredFour to six capabilities, each named as it appears in the docs, with one sentence and a link to the page that explains it.
- Languages and platforms supported Multiple choice, requiredTick every runtime or platform the tool officially supports, not those that merely work. Name versions in the next field.JavaScript or TypeScriptPythonGoRustJava or KotlinC# or .NETLinuxmacOSWindows
- Version and platform details Long textMinimum runtime versions, supported operating systems and any known issues. Copy from the docs so the page and the docs agree.
- Comparison with alternatives Long textA fair table of what the tool does and what others do, with the version of each tool you compared. Link to the method used for any benchmark.
- What the tool does not do Long textLimits an engineer will hit, such as missing platform support or a feature on the roadmap. Saying it early saves support threads.
- Architecture diagram File uploadA diagram of how the tool fits into a typical setup, as SVG or an editable file. Check it matches the current version.
Install and quickstart
This is the page that decides whether a visitor becomes a user, and its commands must work on a clean machine.
- Install commands per platform Long text, requiredThe exact commands for each package manager and operating system, copied from a clean test run. List the package names as they appear in the registry.
- Quickstart steps Long text, requiredFrom install to a first result in five steps or fewer, each with the expected output. Test the steps on a new machine before you send them.
- Sample project repository LinkThe address of a small repository a reader can clone and run. Check that its README matches the quickstart.
- Interactive playground link LinkA browser sandbox or a CodeSandbox link, if one exists. Test that it opens without an account.
- Tested on a clean machine Yes or no, requiredConfirm someone who did not write the tool followed the quickstart and reached the expected output.
Docs and examples
Docs usually live in another system owned by another team, so the site needs to link to them and not try to copy them.
- Documentation address Link, requiredThe home page of the docs. Say what tool builds them, such as Docusaurus or Mintlify, and who can change its theme.
- Who owns the docs Short text, requiredThe person or team that approves changes to the docs, and how long a request takes. The designer will need them for style alignment.
- Featured guides and tutorials Long textThree to six pages from the docs that you want promoted on the site, each with a one-line description.
- Code examples repository LinkThe repository of examples. Tell the designer which are maintained and which are old.
- Code font and theme FontThe monospace font and syntax colours used in the docs, so code blocks on the site look the same.
Pricing and licence
Engineers read the licence before the price, and a free tier with unclear limits is a common cause of angry issues.
- Licence of the tool Single choice, requiredPick the licence on the repository. If the tool has more than one component, answer for the core and note the rest.MITApache 2.0GPL or AGPLSource availableProprietary
- Plans and prices File uploadA table with each plan, price, billing period and limits such as seats, runs or storage. Say what changes at each tier.
- Free tier limits Long textThe exact limits of the free plan and what happens when a user exceeds them, whether throttling or a bill.
- Commercial use rules Long textWhat a company may do for free and when it has to pay. Have the licence owner approve the wording.
- Do prices go on the website Yes or no, requiredIf no, say what the page shows instead and who answers the sales form.
Changelog and community
Activity signals that a tool is maintained, so the release notes and community links have to be current and linked from the site.
- Changelog address Link, requiredThe page or repository file that lists releases. The site can pull the latest entry, so say how it is formatted.
- Roadmap or issue tracker link LinkThe public roadmap or the project board. Only link it if the team keeps it current.
- Community channels Multiple choice, requiredTick the places where users get help that a maintainer reads.GitHub DiscussionsDiscordSlackStack Overflow tagForumMailing list
- Support options by plan Long textWho answers, how fast and through which channel for free and paid users. State the response targets only if the team meets them.
- Contributor guidelines LinkThe CONTRIBUTING file or page. Add the code of conduct link next to it.
Security and legal
Company buyers check security and data handling before approving a tool, and engineers check what a tool sends home.
- Vulnerability disclosure contact Short text, requiredThe email or form for reporting a security problem, and the policy that says how fast you reply. Link to a security.txt if you have one.
- Usage data the tool sends Yes or no, requiredSay whether the tool sends telemetry. If yes, describe what is sent and how a user turns it off, because engineers will test this.
- Security certifications held Multiple choiceTick only what you hold today and can show with a report. Skip the ones in progress.SOC 2 Type IIISO 27001Data processing agreement availableSingle sign-onSelf-hosted optionNone yet
- Logo files File upload, requiredSVG files for the full logo, the symbol and a version on dark backgrounds. Include the favicon master.
- Brand colours Colour, requiredThe hex codes for the main and accent colours, and the colour used for code highlights.
- Terms and privacy policy addresses Link, requiredThe live addresses of both documents. If either is a draft, name who is finishing it and the date.
What clients get stuck on
Code samples that do not run
Sample code is copied from old docs and fails on a clean machine. Ask someone who did not write the tool to run every snippet, and keep a note of the version tested.
Benchmarks with no method
Speed claims arrive as a chart in a slide. Ask for the repository, the hardware, the versions and the date, or present the claim as a rough note and not a headline.
Docs owned by another team
The docs site has its own theme, stack and approval route. Ask in week one who can change it, and agree whether the marketing site links out or the docs are restyled.
Telemetry no one has described
Many tools send usage data and nobody has written down what. Ask an engineer for the exact fields and the opt-out, and put it in plain text on the site.
A roadmap that overpromises
Roadmap pages show dates that slip. Ask the product lead which items are committed and keep the rest in a 'planned' list without dates.
Copy the checklist
Plain Markdown you can paste into a doc or an email.
# Developer tools website content checklist
## Home
- [ ] Tool name and tagline (Short text, required)
- [ ] Problem the tool solves (Long text, required)
- [ ] Hero code sample (Long text, required)
- [ ] Primary action (Single choice, required)
- [ ] Hero terminal or interface capture (Image upload)
## Product overview
- [ ] Main capabilities (Long text, required)
- [ ] Languages and platforms supported (Multiple choice, required)
- [ ] Version and platform details (Long text)
- [ ] Comparison with alternatives (Long text)
- [ ] What the tool does not do (Long text)
- [ ] Architecture diagram (File upload)
## Install and quickstart
- [ ] Install commands per platform (Long text, required)
- [ ] Quickstart steps (Long text, required)
- [ ] Sample project repository (Link)
- [ ] Interactive playground link (Link)
- [ ] Tested on a clean machine (Yes or no, required)
## Docs and examples
- [ ] Documentation address (Link, required)
- [ ] Who owns the docs (Short text, required)
- [ ] Featured guides and tutorials (Long text)
- [ ] Code examples repository (Link)
- [ ] Code font and theme (Font)
## Pricing and licence
- [ ] Licence of the tool (Single choice, required)
- [ ] Plans and prices (File upload)
- [ ] Free tier limits (Long text)
- [ ] Commercial use rules (Long text)
- [ ] Do prices go on the website (Yes or no, required)
## Changelog and community
- [ ] Changelog address (Link, required)
- [ ] Roadmap or issue tracker link (Link)
- [ ] Community channels (Multiple choice, required)
- [ ] Support options by plan (Long text)
- [ ] Contributor guidelines (Link)
## Security and legal
- [ ] Vulnerability disclosure contact (Short text, required)
- [ ] Usage data the tool sends (Yes or no, required)
- [ ] Security certifications held (Multiple choice)
- [ ] Logo files (File upload, required)
- [ ] Brand colours (Colour, required)
- [ ] Terms and privacy policy addresses (Link, required)
Questions about this checklist
Should the docs live on the marketing site?
Usually on a subdomain or a separate path, built by the docs tool, with shared header and colours. Mixing them in one CMS makes releases and search harder for both teams.
What belongs on the home page of a developer tool?
A description, a runnable code sample, an install command and links to the docs. Engineers want to try the tool, so every extra section before the install button costs visits.
How do we show benchmarks fairly?
Publish the repository, the hardware and the versions, and show the date. If the numbers shift with setup, show a range, and let readers run the benchmark themselves.
Related checklists
API product
An API product site has to show a working request and response, explain how to get a key and state limits, prices and uptime in plain terms. Most delays come from docs owned by engineering, SLA figures and unclear rate limits.
SaaS landing page
A SaaS landing page has to say who the product is for, show it working and give a price or a clear next step. Real screenshots, customer permission to use names and a pricing page that is still changing cause most of the delay.
Open source project
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.