Skip to content

docs: improve workspaces and templates doc#9139

Merged
matifali merged 42 commits into
coder:templates-docsfrom
marcpaq:templates-docs
Oct 16, 2023
Merged

docs: improve workspaces and templates doc#9139
matifali merged 42 commits into
coder:templates-docsfrom
marcpaq:templates-docs

Conversation

@marcpaq
Copy link
Copy Markdown
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
Copy Markdown

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
Comment thread docs/workspaces.md Outdated
bpmct
bpmct approved these changes Aug 16, 2023
View reviewed changes
Comment thread docs/workspaces.md Outdated
Comment thread docs/workspaces.md
@matifali
Copy link
Copy Markdown
Member

matifali commented Aug 23, 2023

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
Comment thread docs/workspaces.md Outdated
matifali
matifali reviewed Aug 23, 2023
View reviewed changes
Copy link
Copy Markdown
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

Comment thread docs/workspaces.md Outdated
Comment thread docs/workspaces.md Outdated
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
Copy Markdown
Contributor Author

marcpaq commented Aug 25, 2023

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

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
bpmct reviewed Sep 8, 2023
View reviewed changes
Comment thread docs/templates/tutorial.md
@bpmct
Copy link
Copy Markdown
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 reviewed Oct 4, 2023
View reviewed changes
Comment thread docs/templates/parameters.md Outdated
matifali
matifali reviewed Oct 4, 2023
View reviewed changes
Comment thread docs/templates/parameters.md Outdated
matifali
matifali reviewed Oct 4, 2023
View reviewed changes
Comment thread docs/templates/resource-persistence.md
matifali
matifali reviewed Oct 4, 2023
View reviewed changes
Comment thread docs/templates/tour.md
matifali
matifali reviewed Oct 4, 2023
View reviewed changes
Comment thread docs/templates/tour.md
matifali
matifali reviewed Oct 4, 2023
View reviewed changes
Comment thread docs/templates/tour.md
matifali
matifali reviewed Oct 4, 2023
View reviewed changes
Comment thread docs/templates/tour.md
matifali
matifali approved these changes Oct 4, 2023
View reviewed changes
Copy link
Copy Markdown
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
Copy Markdown
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.

Comment thread docs/templates/parameters.md Outdated
Comment thread docs/templates/parameters.md Outdated
Comment thread docs/templates/parameters.md Outdated
@matifali matifali mentioned this pull request Oct 9, 2023
Closed
@matifali
Copy link
Copy Markdown
Member

matifali commented Oct 10, 2023

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
Comment thread docs/workspaces.md Outdated
bpmct
bpmct requested changes Oct 15, 2023
View reviewed changes
Copy link
Copy Markdown
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
Comment thread 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
Copy Markdown
Member

@matifali matifali Oct 16, 2023

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
Copy Markdown
Member

@matifali matifali Oct 16, 2023

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
Copy Markdown
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