Write the docs as a quick start, not a policy. Lead with the commands a developer runs, show what a pass and a failure look like, and give a short fix guide for every check that can block. Put the reasons after the steps.
What the CNCF paper asks for
The CNCF platforms white paper says documentation is a key aspect of a successful platform, that users need documentation and examples, and that a platform should provide tools to speed up onboarding of new projects. Its example of a reusable supply chain workflow comes with an initial project template and documentation. Docs are part of the product, not an afterthought.
Backstage lists TechDocs among its out of the box features, describing a docs like code approach: docs live beside the code and go through the same review. That is a good pattern for any platform, portal or not.
Structure that works
| Section | Contents | Length |
|---|---|---|
| Quick start | Create a service, run the first scan, open the first pull request | One screen |
| What the checks do | One line per check, with its level: block, warn or inform | One table |
| Fix guides | One short page per blocking check | Under 300 words each |
| Exceptions | How to ask, what is needed, how long it lasts | Half a page |
| Why | The risk each control reduces | Short paragraphs |
| Contact | Channel and expected response time | Two lines |
Steps
- Write the quick start first and test it with someone who has never seen the platform.
- List every check that can block. If a check has no fix guide, you have a support ticket waiting to happen.
- In each fix guide, show the exact failure message, the cause, and the command or edit that resolves it.
- Link the fix guide from the failure message itself.
- Add a changelog so teams can see when rules changed.
- Review the docs after each incident or support spike and fix the gaps found.
Habits that kill readership
- Opening with a policy statement and compliance references. Put those at the end.
- Screenshots that go stale. Prefer commands and text.
- Long pages that mix beginner and advanced material.
- No date. A reader cannot tell if the page is current.
- Fix guides that say "contact security" with no detail.
Measure whether it works
Count support questions per week, and tag each with the doc page that should have answered it. If one page keeps appearing, rewrite it. Track the share of new services that complete the quick start without help. See why developers skip the paved road for the other half of the problem.
Where Safeguard fits
Safeguard's CLI and IDE extensions show findings where developers work, and its policies and gates can link a failure to your own fix guide. Try a free scan at gold.safeguard.sh/scan.
Try it yourself
Open the demo and read the failure message as a developer would. Ask what link or hint would make the next step obvious.
Click through it at your own pace, or open it full screen.
Quick check
How long should a fix guide be?
Short enough to read at the moment of failure, often under 300 words with the exact message and the fix.
Where should docs live?
Beside the code, reviewed like code. Backstage's TechDocs follows the docs like code approach.
Sources
Last reviewed: 19 October 2026.
