Write a software handoff README Buyers can run
A software handoff README should take a Buyer from the files they receive to a result they can check. Name the required versions and accounts, give the setup steps in order, explain configuration, and show what success looks like. Then follow those instructions using a fresh copy of the exact files you're selling.
Start with one useful workflow. A long feature list won't explain why a form submission disappeared after a reload. A short, repeatable example can show where the data goes and what the Buyer still needs to configure.
What belongs in a software handoff README?
Document the shortest complete route to using the software, including its limits. GitHub's README guidance covers purpose, use, help, and maintenance. For a paid source delivery, add the details someone needs to run their own copy.
Use this worksheet before polishing the prose:
| Section | What to write |
|---|---|
| Included files | Application folders, database migrations, sample data, documentation, and anything supplied separately |
| Tested delivery | Commit, release, or bundle identifier, plus the date you checked it |
| Requirements | Runtime and package-manager versions you actually used, supported operating system, required services and accounts |
| First run | Ordered commands, where to run them, and what each step changes |
| Configuration | Each setting's purpose, where to obtain it, and whether the browser may receive it |
| Success check | An action, its expected saved result, and how to check that result after a reload |
| Deployment | What differs from local use: hosting, database, storage, callbacks, scheduled work, and account approvals |
| Limits and help | Known gaps, optional features, support included, and where to ask a question |
Keep longer instructions in linked files such as docs/deployment.md. Link to documentation included in the delivery, or confirm the Buyer can access its location. A private page in your own account won't help them.
If you're still choosing which software to sell, what to sell on Zero to Hundred covers the scope question. The README explains the particular software you've chosen.
Which setup steps need to be explicit?
Write every step that a fresh copy needs, in the order someone must perform it. Include the working directory, dependency installation, configuration, database preparation, and the process that serves the app. Name any background worker that also needs to run.
Avoid instructions such as “install the dependencies and run it.” Record the package manager and version you checked. For software using npm with a compatible lockfile, npm ci installs from that lockfile and fails when it disagrees with package.json. Document any install flags the software needs. Other package managers need their own checked instructions.
Use the actual script names from your delivery. A command called migrate in another app might be called something else in yours. Explain whether database preparation creates tables, changes existing data, or adds sample records. Give the first-run instructions for a separate empty database so a reader doesn't point them at existing customer data.
Place an observable result beside each important step. “The server starts” is incomplete if the app also needs a worker. Say which local URL opens, what initial screen appears, and which features remain unavailable until another service is configured.
How should you document configuration without sharing secrets?
List the setting names and explain how the Buyer supplies their own values. Keep working credentials out of the README, screenshots, sample files, and source delivery. The Twelve-Factor configuration guidance separates code from settings that change between deployments, including database connections and external-service credentials.
Here's an illustrative configuration table for a small web app. The names and behavior are examples, not settings required by Zero to Hundred or evidence about a particular listing:
| Setting | Used by | Required for | What the instructions should explain |
|---|---|---|---|
APP_BASE_URL | Server | Links back to the app | The local value and where to change it for deployment |
DATABASE_URL | Server only | Saving records | How to create a separate database and obtain its connection details |
EMAIL_API_KEY | Server only | Sending email | Where to create the Buyer's key and what happens when email isn't configured |
Use placeholders in an example configuration file. State which settings are safe to expose to the browser and which must stay on the server. Required and optional settings need different instructions: a feature that needs an outside account shouldn't look complete when that account is absent.
If a credential has already leaked, removing it from the README isn't enough. GitHub's remediation guidance calls for revoking or rotating the credential. Check the delivery again after fixing the leak.
What proves that the first run worked?
Give the reader a small task with an expected result they can inspect. Choose a task that represents the software's main purpose. Explain what it checks and what still needs separate verification.
For example, imagine software that collects quote requests. Its first-run check could be:
- Start a separate local copy with an empty database and synthetic sample data. Keep real email and payment actions disabled for this rehearsal.
- Open the request form and submit a clearly labelled sample request.
- Open the request list. Confirm the submitted details appear once.
- Reload the page and reopen the request. Confirm the saved details remain.
- Restart the app and check the request again.
That example checks a path from input to persistent storage. It doesn't establish access control, email delivery, payment behavior, or readiness for real users. Those need their own checks. The Buyer checklist for evaluating an app covers the wider review before launch.
Add troubleshooting for failures you've actually encountered. Use a table with the visible symptom, a likely cause you've confirmed, and the next check. For example, an app that loads while its request list stays empty may need a database connection or migration. Verify the cause in your software before documenting it as the answer.
What should a Buyer see before purchasing?
Put the requirements and important limitations in the public listing as well as the delivered documentation. A Buyer needs to know about a required paid service, account approval, unsupported operating system, or unfinished feature before deciding to pay.
Keep the full configuration instructions with the source, using placeholders throughout. Public screenshots can show a representative workflow with synthetic data. Label sample data and describe any difference between the public demo and the version being delivered. Keep customer records and account credentials out of both.
On Zero to Hundred, the Buyer receives source after payment. The purchase terms govern that transaction. A public requirements summary helps the Buyer assess setup work before source access; a delivered README helps them perform it afterward. Neither document should promise rights, hosting, updates, or support beyond what's actually included.
How do you check the README before selling?
Rehearse the handoff from the exact delivery, without relying on your existing machine's saved configuration. A fresh folder alone won't expose a missing step if your shell already has the required keys or your database already contains every table.
Use a separate disposable setup and record these checks:
- The delivery identifier matches the version described in the README.
- The documented runtime and dependency steps work without unlisted local files or private packages.
- Configuration comes from the documented locations, using separate accounts or local substitutes where supported.
- The first-run task produces the expected result after a reload and restart.
- Deployment requirements and any untested hosting targets are stated accurately.
- The README, public requirements summary, and known limitations agree.
Ask someone unfamiliar with the software to follow the instructions if you can. Record every point where they need an answer from you, then put that answer in the right step. An AI assistant can help edit the text; running the delivered version checks whether the instructions match the software.
Repeat the affected steps when a dependency, configuration setting, or setup command changes. Update the checked date only after checking them. A README is ready when another person can follow the path you've described and tell where their own work begins.
Prepare that path, then see how selling works.
