Problem
Multiple vendors hit doc issues during onboarding that cost them time. Bundling these because they're all the same category: the docs say one thing, reality is another.
Evidence
| Finding |
Location |
Issue |
| replicated release create --yaml-dir . --promote Unstable –version has an em-dash (–) instead of double-dash (--). Command fails when copy-pasted. |
docs.replicated.com/vendor/replicated-onboarding |
Copy-paste broken |
| GitHub credentials setup not immediately apparent - where to provide them? |
docs.replicated.com/vendor/ci-overview |
Missing setup steps |
| "Couldn't get airgap builds. Not clear where to set this up immediately" |
Airgap / CI docs |
Missing setup steps |
| AI struggled with KOTS config syntax: {? {repl ConfigOptionEquals "database_bundled" "1": ''} : ''} instead of '{{repl ConfigOption "storage_bundled" | ParseBool}}'. Vendor had to manually point AI at docs. |
KOTS config docs |
Syntax not prominent / AI-hostile |
Source
Evans (bootcamp friction log)
Proposed fix
- Em-dash: Search docs repo for Unicode em-dashes (
– and —) in code blocks and replace with ASCII dashes. Add a lint check. - GH credentials: Add a prominent "Before you start" section to the CI overview doc listing the credentials/secrets needed and where to configure each.
- Airgap setup: Add a linked "Enable airgap builds" page from the CI overview
- KOTS config syntax: Add a "Common template patterns" page with copy-pasteable snippets for the most common patterns. Mark legacy syntax as deprecated where applicable.
Problem
Multiple vendors hit doc issues during onboarding that cost them time. Bundling these because they're all the same category: the docs say one thing, reality is another.
Evidence
Source
Evans (bootcamp friction log)
Proposed fix
–and—) in code blocks and replace with ASCII dashes. Add a lint check.