Most support tickets for source code products are not bugs. They are installation problems, configuration questions and "how do I change X" requests that a few well-placed pages would have answered. Good software documentation for customers is organized around those questions: what the buyer needs to install the app, configure it, use it, customize it, upgrade it and fix it when something goes wrong.
Documentation also affects whether people buy at all. It is one of the trust signals described in our guide on how to sell your web app or SaaS source code, and reviewers on AppTrovo check for clear installation and usage instructions before a product is listed. This guide shows you what to write, in what order, and how to keep it accurate with almost no extra effort.
The goal is not more pages. It is fewer tickets per sale, which is what makes a one-time license profitable over time.
Which documents does a code product need?
Buyers of source code arrive with different goals at different times. Separate your documentation by goal so each reader finds their answer quickly. The DiΓ‘taxis framework is a well-known model for this split between tutorials, how-to guides, reference and explanation. For a sellable web app, six documents cover almost everything:
| Document | Reader's question | Prevents tickets like |
|---|---|---|
| README / Quick start | What is this and how do I get it running? | "Where do I start?", "Which file do I upload?" |
| Installation guide | How do I install it on my server, step by step? | "Blank page after upload", "Database connection error" |
| Configuration reference | What does each setting and environment variable do? | "Emails are not sending", "How do I change the currency?" |
| User guide | How do I do a task in the app? | "How do I add a staff member?", "Where are reports?" |
| Customization guide | How do I change the code safely? | "How do I change the logo?", "How do I add a field?" |
| Troubleshooting and upgrade notes | Something broke, or I want the new version | "500 error after update", "Queue jobs not running" |
Ship the docs inside the download (a docs/ folder or an HTML file) and publish the same content online. Buyers searching for an error message will find a public page; buyers on a server without internet access can still read the local copy.
Start with a README written for buyers
Your repository README was probably written for yourself. A buyer's README answers different questions in the first screen:
- What this is, in one sentence.
- Requirements: language version, extensions, database, cron, queue, any paid third-party services.
- What is in the ZIP: which folder to upload, which is documentation, which is optional (design files, sample data).
- The fastest path to a running app: five to ten lines, linking to the full installation guide.
- Default logins created by the installer, with a reminder to change them.
- Where to get help: documentation link, how to open a support ticket, and what to include in it.
- Version and changelog link.
Installation guide template
The installation guide prevents more tickets than everything else combined. Write it by installing your product on a clean server while you take notes, never from memory. Use this structure:
- Before you begin. A checklist the buyer can tick: server access, PHP or runtime version, required extensions, a database and a user with full privileges on it, a domain pointing at the server, SSL certificate, ability to set up a cron job.
- Upload the files. Say exactly which folder goes where, and which folder must be the web root (for a Laravel app,
public/). Include a note for shared hosting if the web root cannot be changed. - Install dependencies if they are not bundled, with the exact commands, such as
composer install --no-dev --optimize-autoloader. - Create the environment file. Copy
.env.exampleto.envand list the values that must be changed. - Set file permissions. Name the directories that must be writable, for example
storage/andbootstrap/cache/, and explain why rather than recommending 777. - Run the installer or migrations. Show what each installer screen asks for, including the license key step.
- Set up scheduled tasks and queues. Give the exact cron line and how to run or supervise queue workers.
- First login and first tasks. Default credentials, the first three settings to change, and how to send a test email.
- Verify the install. A short list of things that should now work, such as "the dashboard loads", "a test email arrives", "the scheduled task appears in the log".
- If something went wrong: links to the five most common installation errors in your troubleshooting page.
Add a separate short section for each common hosting setup you support: a VPS with Nginx, a VPS with Apache, shared hosting with cPanel, Docker. If you do not support one, say so. Buyers can also learn the general process from guides such as how to install a Laravel web app on a VPS, but your guide must still cover your product's specific steps.
Write a configuration reference, not just comments in .env
Comments in .env.example help developers, but many buyers are business owners or junior developers. A reference table answers "what does this do and when do I change it?" in one place.
| Variable | Default | What it does | When to change it |
|---|---|---|---|
APP_URL | http://localhost | Base URL used in links and emails | Always; set it to your real domain with https |
MAIL_MAILER | log | How emails are sent | Set to smtp or your provider before going live |
QUEUE_CONNECTION | sync | Whether background jobs run immediately or in a worker | Use database or redis on busy sites and run a worker |
APP_TIMEZONE | UTC | Time zone for dates and scheduled tasks | Set to your business time zone |
The table above is an example; document every variable your product reads. Do the same for settings screens inside the app: what each setting changes and what the safe default is.
Troubleshooting: write entries around real error messages
Buyers search for the exact text they see. A troubleshooting page that uses those exact strings as headings gets found by search engines and by the buyer's own site search. Use this format for every entry:
Error:
SQLSTATE[HY000] [2002] Connection refusedWhat it means: the app cannot reach the database server.
Common causes: wrong
DB_HOSTorDB_PORT; the database service is not running; the host only accepts connections from localhost.How to fix: check the values in
.env, confirm the database is running, try127.0.0.1instead oflocalhost, then clear the config cache.
Start with the errors you already know: a white page with debug off, the 500 error after upload, permission errors on storage, the missing PHP extension, mail authentication failures, cron not running, and license verification failures. Then add a new entry each time a ticket reveals a new one.
Customization guide: answer "how do I change X"
Customization requests are the second-largest source of tickets, and many sellers answer them one by one forever. Document the ten most common changes once:
- Change the logo, colors and app name.
- Edit email templates and notification text.
- Add or edit a language or translation string.
- Add a field to a form and to the database.
- Add a menu item or a page.
- Change the currency, date format and number format.
- Connect a different payment, SMS or email provider.
- Add a role or permission.
For each one, show where the file is, what to change and how to keep the change through future updates. That last point matters: if buyers edit core files, every update becomes a support ticket. Point them to extension points, override folders or configuration instead. Our guide to support, updates and versioning covers how to design releases so customized installs can upgrade.
Turn tickets into documentation every month
Documentation goes out of date and never covers everything on the first try. A simple monthly loop keeps it useful:
- Tag every ticket with a category: install, configuration, usage, customization, bug, pre-sale, other.
- Once a month, count the tags. Pick the three most frequent questions that are not bugs.
- Write or improve the page that would have answered each one, using the buyer's own words in the heading.
- Answer future tickets with a link plus a one-line summary. If the link does not solve it, the page needs work.
- Fix the product when the same confusion keeps returning. A clearer error message or installer check is better than any document.
As an illustrative example, a seller receiving 40 tickets a month who finds that 15 are about email configuration can usually remove most of those with one good page and an installer step that sends a test email.
Make the product document itself
The best documentation is the kind the buyer never needs to open:
- Installer checks that test PHP version, extensions, writable folders and database connection, and explain failures in plain language.
- Helpful error messages that say what to do next ("Mail server rejected the login. Check MAIL_USERNAME and MAIL_PASSWORD in Settings").
- A system status page in the admin area showing versions, queue status, last cron run and storage permissions. Buyers can screenshot it when they open a ticket.
- Inline help text next to settings that are easy to misunderstand.
- Empty states that explain the next action ("No staff yet. Add your first staff member").
Style rules that make docs easier to follow
- Write numbered steps for anything done in order, one action per step.
- Show exact commands and exact paths, and say where to run them.
- State the expected result after important steps, so readers know when something went wrong.
- Use screenshots for settings screens, and update them when the interface changes.
- Write in plain US English with short sentences; many buyers read through a translation tool.
- Version the docs. Mark sections that apply only to certain versions, and keep upgrade notes for every release.
The free Write the Docs documentation principles are a good checklist for clarity and structure.
Documentation checklist before you submit
- README answers what, requirements, what is in the ZIP, quick start, default logins and where to get help.
- Installation guide tested on a clean server, with a section for each supported hosting setup.
- Configuration reference covers every environment variable and important setting.
- User guide covers the main tasks for each role.
- Customization guide covers the ten most common changes and how to keep them through updates.
- Troubleshooting page uses exact error messages as headings.
- Changelog and upgrade notes are included.
- Docs are in the download and online.
Before submitting, compare against the product submission checklist and AppTrovo's code standards. When your docs are ready, your listing can link to them from the requirements section, which also helps pre-sale buyers.
Frequently asked questions
What should customer-facing software documentation include?
At minimum: a README, an installation guide, a configuration reference, a user guide, a customization guide and a troubleshooting page with upgrade notes. Each document answers a different question, so keep them separate and link between them.
Should documentation be inside the ZIP or online?
Both. The copy in the ZIP always matches the version the buyer has. The online copy is searchable, easy to link from support replies and can be updated between releases. Make it clear which version each online page applies to.
How detailed should an installation guide be?
Detailed enough that someone who has installed a web app before, but never yours, can finish without contacting you. Include exact commands, paths, required permissions and the expected result after each important step. Test it on a clean server for every release that changes requirements.
How do I know which documentation to write first?
Look at your support tickets and pre-sale questions. Installation and configuration usually come first, followed by the most common customization requests. If you have no tickets yet, install the product yourself on a clean server and document every point where you had to think.
Does good documentation really reduce refunds?
Failed installations and unmet expectations are common reasons buyers ask for refunds, and clear requirements plus a tested installation guide address both. Refunds on AppTrovo follow the refund policy, but preventing the problem is always cheaper than handling the request.