Skip to content

docs: improve dev containers documentation for user start-up #15458

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 39 commits into from
Dec 2, 2024
Merged

docs: improve dev containers documentation for user start-up #15458

merged 39 commits into from
Dec 2, 2024

Conversation

EdwardAngert
Copy link
Contributor

@EdwardAngert EdwardAngert commented Nov 8, 2024 •
edited
Loading

preview

@EdwardAngert EdwardAngert added the docs Area: coder.com/docs label Nov 8, 2024
@EdwardAngert EdwardAngert requested review from mdanter and bpmct November 8, 2024 19:47
@EdwardAngert EdwardAngert self-assigned this Nov 8, 2024
@EdwardAngert EdwardAngert changed the title docs: add new best practice doc to help users get started with dev containers docs: edit devcontainers doc to help users get started with dev containers Nov 8, 2024
@EdwardAngert EdwardAngert marked this pull request as draft November 8, 2024 19:52
@EdwardAngert EdwardAngert changed the title docs: edit devcontainers doc to help users get started with dev containers docs: edit devcontainers doc to help users get started with dev containers [WIP] Nov 8, 2024
bpmct
bpmct reviewed Nov 10, 2024
View reviewed changes
@EdwardAngert EdwardAngert changed the title docs: edit devcontainers doc to help users get started with dev containers [WIP] docs: update devcontainers doc to help users get started with dev containers [WIP] Nov 12, 2024
@EdwardAngert EdwardAngert changed the title docs: update devcontainers doc to help users get started with dev containers [WIP] docs: get users started with dev containers by updating the devcontainers doc [WIP] Nov 12, 2024
@EdwardAngert EdwardAngert changed the title docs: get users started with dev containers by updating the devcontainers doc [WIP] docs: update the dev containers doc to help users get started with dev containers Nov 20, 2024
@EdwardAngert EdwardAngert requested a review from bpmct November 20, 2024 18:05
bpmct
bpmct requested changes Nov 25, 2024
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.

Hey, good start. Left a ton of comments, but please don't get discouraged. I'd also spend some time comparing it to other formatting and styles in our docs.

Of course, our docs style should incrementally change and improve over time, but I think by comparing this to other sections, we'll find good opportunities to improve this PR as well.

docs/admin/index.md Outdated
@@ -15,4 +15,56 @@ and [API](../reference/api/index.md) docs.
For any information not strictly contained in these sections, check out our
[Tutorials](../tutorials/index.md) and [FAQs](../tutorials/faqs.md).

## What is an image, template, devcontainer, or workspace
Copy link
Member

Choose a reason for hiding this comment

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

This may be best presented as a table as this renders quite awkward.

Also I am not sure if this is best on the frontpage of administration. We have no other content here at all. If we do think this is the most important admin concept, we might want to add a sentence explaining why its so important and what else people can expect on the Administration page

Screenshot 2024-11-24 at 9 10 03 PM

Copy link
Member

Choose a reason for hiding this comment

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

This can also be folded into the upcoming Glossay @EdwardAngert is working on.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I can try a table on and see how it feels - I'd tried an html definition list and it looked okay, but everything within the html would also have to be html (like links), and that didn't seem worth it. my concern with tables is how long text shows in cells, but it's worth a shot

the hope is to have this be a glossary component at some point so that we can define terms in place and have them combined into reference pages

here's an example in the MyST docs

Copy link
Contributor Author

Choose a reason for hiding this comment

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

it's also interesting that you're still getting served a build of an older commit :-/ not sure why that is

Copy link
Contributor Author

Choose a reason for hiding this comment

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

adjusted to:

2024-11-26_14-45-53

docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md
Comment on lines +13 to +16
## Layer and image caching

To improve build times, dev containers can be cached. There are two main forms
of caching:
Copy link
Member

Choose a reason for hiding this comment

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

nice-to-have: a diagram could be really neat here!

matifali
matifali reviewed Nov 25, 2024
View reviewed changes
docs/admin/index.md Outdated
@@ -15,4 +15,56 @@ and [API](../reference/api/index.md) docs.
For any information not strictly contained in these sections, check out our
[Tutorials](../tutorials/index.md) and [FAQs](../tutorials/faqs.md).

## What is an image, template, devcontainer, or workspace
Copy link
Member

Choose a reason for hiding this comment

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

This can also be folded into the upcoming Glossay @EdwardAngert is working on.

docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
Comment on lines +127 to +128
Your template can prompt the user for a repo URL with
[parameters](../../extending-templates/parameters.md):
Copy link
Member

Choose a reason for hiding this comment

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

May also mention to use the git-clone module from the registry.

docs/images/templates/template-menu-settings.png Outdated
Copy link
Member

Choose a reason for hiding this comment

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

We have a general image sizing issue through out docs. Related #15495

matifali
matifali approved these changes Nov 25, 2024
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.

Left a few comments to improve. But overall looks great.

EdwardAngert
EdwardAngert commented Nov 25, 2024
View reviewed changes
docs/admin/index.md Outdated
@@ -15,4 +15,56 @@ and [API](../reference/api/index.md) docs.
For any information not strictly contained in these sections, check out our
[Tutorials](../tutorials/index.md) and [FAQs](../tutorials/faqs.md).

## What is an image, template, devcontainer, or workspace
Copy link
Contributor Author

Choose a reason for hiding this comment

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

I can try a table on and see how it feels - I'd tried an html definition list and it looked okay, but everything within the html would also have to be html (like links), and that didn't seem worth it. my concern with tables is how long text shows in cells, but it's worth a shot

the hope is to have this be a glossary component at some point so that we can define terms in place and have them combined into reference pages

here's an example in the MyST docs

docs/admin/index.md Outdated
@@ -15,4 +15,56 @@ and [API](../reference/api/index.md) docs.
For any information not strictly contained in these sections, check out our
[Tutorials](../tutorials/index.md) and [FAQs](../tutorials/faqs.md).

## What is an image, template, devcontainer, or workspace
Copy link
Contributor Author

Choose a reason for hiding this comment

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

it's also interesting that you're still getting served a build of an older commit :-/ not sure why that is

@EdwardAngert EdwardAngert changed the title docs: update the dev containers doc to help users get started with dev containers docs: improve dev containers documentation for user start-up Nov 26, 2024
@EdwardAngert
Copy link
Contributor Author

@matifali looks like the CI is failing due to the broken link introduced in #15610 . I saw your comment about it in that PR - should we hold off on this PR until it's fixed?

@EdwardAngert EdwardAngert requested a review from bpmct November 26, 2024 19:47
@matifali
Copy link
Member

@EdwardAngert docs checks is not a required check and we can merge without it.

Update: the said PR is now merged and the link should work.

@EdwardAngert
Copy link
Contributor Author

EdwardAngert commented Nov 27, 2024 •
edited
Loading

(auto-)merging as a first iteration

@EdwardAngert EdwardAngert enabled auto-merge (squash) November 27, 2024 18:41
@EdwardAngert EdwardAngert merged commit b06d833 into main Dec 2, 2024
24 of 25 checks passed
@EdwardAngert EdwardAngert deleted the bp-dev-containers branch December 2, 2024 17:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@matifali matifali matifali approved these changes

@bpmct bpmct bpmct approved these changes

@mdanter mdanter Awaiting requested review from mdanter

@mattvollmer mattvollmer Awaiting requested review from mattvollmer

@johnstcn johnstcn Awaiting requested review from johnstcn

Assignees

@EdwardAngert EdwardAngert

Labels
docs Area: coder.com/docs
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@EdwardAngert @matifali @johnstcn @bpmct