Skip to content

docs: improve workspaces and templates doc #9139

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 42 commits into from
Oct 16, 2023
Merged

docs: improve workspaces and templates doc #9139

merged 42 commits into from
Oct 16, 2023

Conversation

marcpaq
Copy link
Contributor

@marcpaq marcpaq commented Aug 16, 2023 •
edited
Loading

Hi @bpmct , @kylecarbs

Here's a first draft for the workspaces doc page.

  • reorg: start with conceptual, then getting started asap, then details about managing workspaces
  • more consistent with Coder's contributor guidelines
  • used more 2nd person
  • replaced passive voice with active when it made more sense
  • more consistent terminology
  • a new screenshot, updated a few other screenshots

I have read the CLA Document and I hereby sign the CLA

@cdr-bot cdr-bot bot added the community Pull Requests and issues created by the community. label Aug 16, 2023
@github-actions
Copy link

github-actions bot commented Aug 16, 2023 •
edited
Loading

CLA Assistant Lite bot All contributors have signed the CLA ✍️ ✅

bpmct
bpmct reviewed Aug 16, 2023
View reviewed changes
bpmct
bpmct approved these changes Aug 16, 2023
View reviewed changes
@matifali
Copy link
Member

Hi @marcpaq can you please merge main as I have updated the formatter to enforce an 80 character line length

matifali
matifali reviewed Aug 23, 2023
View reviewed changes
matifali
matifali reviewed Aug 23, 2023
View reviewed changes
Copy link
Member

@matifali matifali left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just a comment about the correct use of shell and console for markdown fenced codeblocks

marcpaq and others added 3 commits August 25, 2023 03:07
@marcpaq @matifali
Update docs/workspaces.md
cb39a6d 
Co-authored-by: Muhammad Atif Ali <matifali@live.com>
@marcpaq @matifali
Update docs/workspaces.md
6706032 
Co-authored-by: Muhammad Atif Ali <matifali@live.com>
@marcpaq @matifali
Update docs/workspaces.md
4e4b9e5 
Co-authored-by: Muhammad Atif Ali <matifali@live.com>
@marcpaq
Copy link
Contributor Author

marcpaq commented Aug 25, 2023

I have read the CLA Document and I hereby sign the CLA

cdrcommunity added a commit to coder/cla that referenced this pull request Aug 25, 2023
@cdrcommunity
@marcpaq has signed the CLA in coder/coder#9139
e13c159
marcpaq added 2 commits August 25, 2023 04:18
@marcpaq
Fixed typos
351c457
@marcpaq
Expanded tutorial
50e9041 
I have read the CLA Document and I hereby sign the CLA
@marcpaq marcpaq changed the title Reorg, updated/new screenshots, consistent terminology Reorg, updated and new screenshots, consistent terminology Aug 28, 2023
@bpmct bpmct changed the title Reorg, updated and new screenshots, consistent terminology docs: workspaces and templates documentation Sep 3, 2023
@bpmct
Copy link
Member

bpmct commented Sep 8, 2023

For the "Advanced: Building your first template" doc:

  • Ephemerality (a disk is kept, but the container is deleted when a workspace is stopped)
  • One or two agent metadata items (CPU, RAM)
  • You can name resources after the workspace name
  • You should bulletproof important resources, like disks, so future template updates don't delete them.

matifali
matifali approved these changes Oct 4, 2023
View reviewed changes
Copy link
Member

@matifali matifali left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have left a few comments, suggestions, and some questions. Overall it looks very good.

matifali
matifali previously requested changes Oct 4, 2023
View reviewed changes
Copy link
Member

@matifali matifali left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Delete the section related to legacy parameters and the migration guide.

@matifali matifali mentioned this pull request Oct 9, 2023
Closed
@matifali
Copy link
Member

Hi @marcpaq, I have deleted the section on legacy parameters. Is there anything blocking you on this? Can you review it once and see if any observations must be addressed?
We should merge this sooner to think about other refactors.

@matifali matifali dismissed their stale review October 10, 2023 09:21

addreseed.

matifali
matifali reviewed Oct 12, 2023
View reviewed changes
bpmct
bpmct requested changes Oct 15, 2023
View reviewed changes
Copy link
Member

@bpmct bpmct left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok I pushed a commit to fix the broken links in the product.

However, did these docs disappear? I think we might need to add a templates/troubleshooting.md back. I am happy to author this and do it first thing tomorrow.

coder/site/src/pages/TerminalPage/TerminalAlerts.tsx

Lines 8 to 88 in 2029543

return (
<TerminalAlert
severity="warning"
dismissible
actions={<RefreshSessionButton />}
>
The workspace{" "}
<Link
title="startup script has exited with an error"
href={docs("/templates#startup-script-exited-with-an-error")}
target="_blank"
rel="noreferrer"
>
startup script has exited with an error
</Link>
, we recommend reloading this session and{" "}
<Link
title=" debugging the startup script"
href={docs("/templates#debugging-the-startup-script")}
target="_blank"
rel="noreferrer"
>
debugging the startup script
</Link>{" "}
because{" "}
<Link
title="your workspace may be incomplete."
href={docs("/templates#your-workspace-may-be-incomplete")}
target="_blank"
rel="noreferrer"
>
your workspace may be incomplete.
</Link>{" "}
</TerminalAlert>
);
};
export const LoadingScriptsAlert = () => {
return (
<TerminalAlert
dismissible
severity="info"
actions={<RefreshSessionButton />}
>
Startup scripts are still running. You can continue using this terminal,
but{" "}
<Link
title="your workspace may be incomplete."
href={docs("/templates#your-workspace-may-be-incomplete")}
target="_blank"
rel="noreferrer"
>
{" "}
your workspace may be incomplete.
</Link>
</TerminalAlert>
);
};
export const LoadedScriptsAlert = () => {
return (
<TerminalAlert
severity="success"
dismissible
actions={<RefreshSessionButton />}
>
Startup scripts have completed successfully. The workspace is ready but
this{" "}
<Link
title="session was started before the startup scripts finished"
href={docs("/templates#your-workspace-may-be-incomplete")}
target="_blank"
rel="noreferrer"
>
session was started before the startup script finished.
</Link>{" "}
To ensure your shell environment is up-to-date, we recommend reloading
this session.
</TerminalAlert>
);
};

Otherwise, I think we're good to merge

matifali
matifali reviewed Oct 16, 2023
View reviewed changes
docs/templates/creating.md

As well as Coder's starter templates, you can see a list of community
templates by our users
[here](https://github.com/coder/coder/blob/main/examples/templates/community-templates.md).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we also mention registry.coder.com/templates?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

cc: @bpmct

bpmct
bpmct approved these changes Oct 16, 2023
View reviewed changes
Copy link
Member

@bpmct bpmct left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed the links - we're all good to merge :)

@matifali matifali merged commit 3279747 into coder:templates-docs Oct 16, 2023
@github-actions github-actions bot locked and limited conversation to collaborators Oct 16, 2023
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Reviewers

@matifali matifali matifali approved these changes

@mtojek mtojek mtojek left review comments

@bpmct bpmct bpmct approved these changes

Assignees

@marcpaq marcpaq

Labels
community Pull Requests and issues created by the community.
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@marcpaq @matifali @bpmct @mtojek