Security tool onboarding docs should answer five questions on one page: how do I install it, how do I run my first scan, how do I read a result, how do I dismiss or fix a finding, and who do I ask. Everything else belongs behind a link.
Why one page
Developers read onboarding docs once, usually while trying to finish something else. A ten page guide is a reference, not onboarding. If the first page does not get someone to a working first scan in a few minutes, they may never come back.
The outline
1. What this tool does for you, in two sentences. Say what it checks and when. Example: "It scans dependencies and code on each pull request and in your editor. It blocks a merge only for new high risk findings."
2. Install, with copy and paste commands. One block per environment: editor extension, command line, CI. Show the expected output so people know it worked. State the supported versions you have verified.
3. Run your first scan. One command, one expected result, one screenshot or output sample. Include what a clean result looks like, since many people have never seen one.
4. How to read a finding. A short annotated example.
| Part | What it tells you |
|---|---|
| Title | What is wrong |
| Location | File and line, or dependency and version |
| Why it matters | One sentence of impact |
| Fix | The suggested change |
| Status | New or existing |
5. How to act on it. Three paths, in this order: fix it, ask for a dated exception, report it as wrong. Link each to a short procedure.
6. What blocks a merge, and what does not. State the gate rule in a sentence. Surprises here create the most resentment.
7. Who to ask. A channel name, office hours time and a named person. Our post on security office hours covers a format.
Keep it honest and current
- Put a "last verified" date at the top and review it each quarter.
- Test the instructions on a clean machine by someone who did not write them.
- Link to a changelog so changes to rules do not surprise people.
- Do not claim the tool catches everything. Say what it covers and what it does not.
Extra sections that earn their place
A short "common problems" list helps most. Include the three questions your support channel gets every week, such as proxy settings, large monorepos, and why a scan differs between laptop and CI.
A glossary of five terms, such as reachable, transitive, exception and advisory, prevents most confusion.
Where this fits
Onboarding docs are part of the developer experience of a tool. A tool with good detection and bad docs will still lose to a weaker tool that people can start in five minutes.
Safeguard publishes install options for Desktop, a CLI with curl and PowerShell installers, VS Code, JetBrains and Open VSX extensions, browser extensions and mobile apps on safeguard.sh/download, which gives a team one place to point new developers.
Quick check
Should onboarding docs include every setting?
No. Link to a full reference. Onboarding is for the shortest path to a working first scan.
Who should write them?
A developer who recently onboarded. They remember what was unclear, and the experts do not.
Last reviewed: 19 October 2026.
