docs: add a Customize your template series under Get started#26712
Conversation
Docs preview📖 View docs preview for |
nickvigilante
left a comment
There was a problem hiding this comment.
Requesting changes.
…, and preposition rules Address review feedback from the Quickstart Part 2 experiment (#26712): - formatting.md: a command with no output uses `sh`, not `console`; `console` requires shown output with `$` prefixes; `sh` is the canonical shell label over `bash`/`shell`; document the generated CLI-reference exception. Add a "Learn more / See also" list example (link fragments, no terminal periods, no leading "Or", clean lead-in stem). - capitalization-and-punctuation.md: new Commas section covering the introductory-element comma, no comma in a short compound predicate, the Oxford comma, and a note that semantic line breaks never change punctuation. - word-choice.md: prefer "learn" or "find out" over "see" for comprehension outcomes. - audience-and-scope.md: give the audience only what it needs; do not add wrong-role caveats when the audience already has the access. - voice-and-tone.md: reframe trailing prepositions as a judgment call with examples in both directions. Refs: DOCS-434 Filed via Coder Agents on Nick's behalf.
nickvigilante
left a comment
There was a problem hiding this comment.
Changes requested.
39b5f58 to
81087b5
Compare
|
/coder-agents-review |
|
Chat: Review posted | View chat Review history
deep-review v0.9.0 | Round 1 | Last posted: Round 1, 2 findings (1 P2, 1 Nit), COMMENT. Review Finding inventoryFinding InventoryFindings
Law analysisEffective LOC: 1660 (raw), ~1280 (true new). Head SHA: 9bfa93c. Verdict: Don't split. Enforcement: N/A. Single risk domain (docs), tight content coupling across cross-linked guides, no valid vertical or horizontal slices without leaving broken links on published pages. Round logRound 1Netero-only. 1 P2, 1 Nit. Reviewed against a163d43..9bfa93c. About deep-reviewCRF = Coder Review Finding (P0-P4, Nit, Note)
|
nickvigilante
left a comment
There was a problem hiding this comment.
Changes requested.
There was a problem hiding this comment.
First-pass review (Netero). This is a mechanical scan only; the full review panel has not yet reviewed this PR. The panel will review after these findings are addressed.
The restructure is well-organized: the series hub, the four Part 2 guides, and the manifest wiring all hang together cleanly. The cross-linking between guides is consistent, and the persistence concept is properly owned by a single guide with cross-references from others.
1 P2, 1 Nit.
The P2 is the main blocker for panel review: four files still point at the old tutorials/quickstart.md path, which no longer exists after the rename.
"The
docker.mdlink is the worst: its#cannot-connect-to-the-docker-daemonanchor now lives inlaunch-workspace.md, notindex.md, so even if the docs framework redirectsquickstart.mdtoquickstart/index.md, the fragment resolves to nothing." (Netero)
docs/install/docker.md:114
P2 [CRF-1] Four files outside this PR still link to the deleted tutorials/quickstart.md path:
docs/install/docker.md:114:../tutorials/quickstart.md#cannot-connect-to-the-docker-daemondocs/install/index.md:11:../tutorials/quickstart.mddocs/admin/templates/managing-templates/index.md:4:../../../tutorials/quickstart.mddocs/README.md:187:./tutorials/quickstart.md
This one is the sharpest: the #cannot-connect-to-the-docker-daemon fragment lives in launch-workspace.md, not index.md. Even if the docs framework implicitly redirects quickstart.md to quickstart/index.md, the anchor resolves to nothing.
All four need to be updated to point at the correct file in the new quickstart/ directory. (Netero)
🤖
🤖 This review was automatically generated with Coder Agents.
nickvigilante
left a comment
There was a problem hiding this comment.
Changes requested.
Documentation CheckUpdates NeededPrevious items addressed (merged to main via #26821 and related commits):
Current PR scope (as of 85047d2) adds new content under Automated review via Coder Agents |
|
From Coder Agents: Addressed the doc-check findings in 19a5c5b. Repaired all five inbound links left by the Quickstart split, choosing each target by intent:
One item to confirm on your side: the public redirect. |
aslilac
left a comment
There was a problem hiding this comment.
in general prs that add over 1000 lines of code are impossible to review well and that includes documentation. you'll get a much better end result if you approach this in smaller chunks.
Incorporate actionable review feedback from #26712: - launch-workspace: set DOCKER_HOST to Colima's socket and persist it to the shell profile during macOS setup, so the server reaches Docker on the first try. Wrap the "Address already in use" steps in tabs and make the Linux path find and stop the process on the port like macOS and Windows. - quickstart index: add a Next steps pointer to part 1 so the landing page does not dead-end. - add-a-language: drop hard-coded main.tf line numbers, which rot when the file changes, and note the deployment /icons browser for icon paths. - install-command-line-tools: confirm brew before installing mise; keep the restart reconnect on the web terminal instead of switching to coder ssh. - personalize-with-dotfiles: note that a dotfiles repo can install personal utilities via an install script, not just config files. - authenticate-to-github: retitle to the outcome "Clone private repositories", clarify that public repos clone out of the box, explain external auth and the built-in GitHub app, and fix the final page's next step since it is the last guide in the series. Refs: DOCS-458 Filed via Coder Agents on Nick's behalf.
@aslilac I'll break this PR up into smaller chunks, and when it gets to the Homebrew/Mise PR, I'll tag you for review. |
9c68e3b to
85047d2
Compare
|
From Coder Agents: Heads-up that this PR was force-pushed as a restructure (tip What changedThe series was rebuilt from
Because the files moved, the line-anchored threads from the old tree are now outdated. The net diff is the four guides above plus the Review feedback addressed
Handled separately
|
Move the multi-page Quickstart customization series to docs/get-started/customize-your-template/, nested under the top-level Get started section, now that the single-page Quickstart lives at docs/get-started/index.md. - Drop the redundant Part 1 launch page; the merged Quickstart covers it. - Archive the dotfiles guide out of the series and remove its inbound links. - Rename the section to "Customize your template". - Add a Ruby preset alongside the Ruby parameter in add-a-language. - Route the parameter change through Workspace settings > Parameters. - Give each page a "What's next?" step so the series reads as a sequence. Filed via Coder Agents on Nick's behalf.
85047d2 to
b23486c
Compare
Add a Step 5 to the Install command-line tools guide that installs ripgrep and bat from the template on every start, so every new workspace ships with them without manual setup. mise is the default because it installs into the persistent home directory; a Homebrew and Brewfile alternative reuses the Step 4 volume. Pin both tools to latest and add the install_tools coder_script to the embedded main.tf. Filed via Coder Agents on Nick's behalf.
Align the embedded main.tf in the Customize your template series with examples/templates/quickstart/main.tf, which dropped the vscode-desktop option and module in #26789. Removes the VS Code Desktop IDE option and its module from all three guides so the docs match the shipped template. Filed via Coder Agents on Nick's behalf.
1e9f17e to
0b79664
Compare
bpmct
left a comment
There was a problem hiding this comment.
Approving now, but we're missing some important things:
- The "Quickstart" landing page does not intuitively link people to "Customize your template." This page is not that discoverable
- I think as a fast-follow we should explain the image management topic we discussed earlier today and in the review comments around when to use an image vs scripts in the template, and how to use other base images and how to build custom ones
|
Oh and the flow is very solid @nickvigilante! I think we do a great job covering the topics and concepts for new users |
b264e25 to
d177bc5
Compare
d177bc5 to
8b97003
Compare
What
Adds a Customize your template series under the top-level Get started section, at
docs/get-started/customize-your-template/.These guides extend the single-page Quickstart (added in #26821) with hands-on template customization:
Changes from the earlier draft
This branch was rebased onto the consolidated
/docs/get-startedstructure:tutorials/quickstart/toget-started/customize-your-template/, nested under the new Get started section.get-started/index.md, docs: add top-level Get started section and move the Quickstart #26821) already covers them.Still open / follow-ups
Decision log
tutorials/quickstart/: the Quickstart now lives at/docs/get-started, so the series belongs under the same top-level section for a single, coherent entry point.get-started/index.mdin docs: add top-level Get started section and move the Quickstart #26821; keeping a second copy would duplicate and drift.Generated by Coder Agents on behalf of @nickvigilante.