Yes. A quickstart should get a reader to a working result fast and say plainly that it is for local use. A separate production guide should list what changes before real traffic: credentials, network exposure, logging, updates. Mixing them either bloats the quickstart or hides the safety steps.
Two readers, two jobs
A quickstart reader is deciding whether your product works for them. They want a result in minutes, and every extra step costs attention. A production reader already decided. They want completeness, and extra steps are welcome when they matter.
When a single page serves both, one of them loses. If it is long, the evaluator leaves. If it is short, the production reader copies the local settings into a live system, which is how a development configuration ends up on the internet.
What the quickstart should include
- A clear first line stating that it sets up a local test environment.
- Safe by default settings where the choice costs nothing: bind to the loopback address, no sample accounts with shared passwords, no real credentials in files.
- Secrets read from the environment, not typed into source.
- A prominent link, near the end and also near any risky step, to the production guide.
The CISA Secure by Design publication frames this as a manufacturer responsibility. Its three principles are taking ownership of customer security outcomes, embracing radical transparency and accountability, and leading from the top. A quickstart that quietly teaches an unsafe default is a small failure of the first principle.
What the production guide should include
| Topic | Question it answers |
|---|---|
| Credentials | Where do secrets live and how are they rotated? |
| Network exposure | What listens on which interface, and what sits in front? |
| Authentication | What must be switched on that the quickstart left off? |
| Logging | What is recorded, and what must never be? |
| Updates | How are patches applied and how do you learn of advisories? |
| Backups and recovery | What is backed up, and has restore been tested? |
Write it as a checklist so a reader can tick through it. Each item should link to the detailed reference page.
Keep them from drifting apart
Quickstarts and production guides decay at different rates. Tie both to the same sample configuration file where possible, so a change to a default shows up in both. When a default changes, add a line to the changelog and update the production guide the same day.
Add a test to the docs build that runs the quickstart steps in a clean environment. If the quickstart breaks, the build breaks.
Signals that you need to split
A quickstart that has grown past ten steps. A page where "optional" appears in several places. A support queue full of questions about a setting the quickstart told people to skip. An incident where a reader deployed a sample as it was.
For structure advice see docs site structure: four reader needs.
Try it yourself
Continuous monitoring is one production topic a quickstart rarely covers. Click through to see what ongoing checks look like.
Click through it at your own pace, or open it full screen.
Safeguard offers continuous monitoring, dependency scanning and SBOM generation for the projects your docs describe. The free scan is at https://gold.safeguard.sh/scan.
Quick check
Can one page do both jobs with a good table of contents?
It can, but it usually pushes the safety steps below the fold. Two pages with clear links serve both readers better.
What is the one line every quickstart needs?
A statement that it is for local testing, with a link to what changes for production.
Sources
Last reviewed: 19 October 2026.
