replicatedhq / replicatedhq/replicated-docs
Onboarding docs accuracy pass - command errors, missing setup steps, AI-confusing syntax
Nobody has claimed this yet.
- Dominant language
- MDX
- Stars
- 12
- Forks
- 35
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 113
Description
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.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Review the vendor onboarding, CI overview, Airgap/CI, and KOTS config documentation locations named in the issue, then search the docs repository for em-dashes in code blocks. Update the copy-paste command, credential and airgap setup guidance, and common KOTS syntax examples; add the requested lint check and links, with all listed onboarding paths providing accurate, discoverable instructions.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 52/100