docs: improve dev containers documentation for user start-up by EdwardAngert · Pull Request #15458 · coder/coder

EdwardAngert · 2024-11-08T19:47:50Z

TODO: verify and expand What is an image, template, devcontainer, or workspace
TODO: verify and expand ## Add a devcontainer template to Coder
TODO: verify and expand ## Layer and image caching
TODO: link to and edit dotfiles doc
TODO: https://github.com/coder/coder/pull/15458/files#diff-be0dd9ff983020129c7a94c628a0fc4a397a9bbc8b5eec92ec38f4b8c83fe167R10

docs/manifest.json

bpmct

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/manifest.json

docs/admin/index.md

bpmct · 2024-11-25T03:11:10Z

docs/admin/index.md

 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


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

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

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

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

adjusted to:

docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md

docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md

bpmct · 2024-11-25T03:25:13Z

docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md

+## Layer and image caching
+
+To improve build times, dev containers can be cached. There are two main forms
+of caching:


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

docs/admin/templates/managing-templates/devcontainers/index.md

matifali · 2024-11-25T09:58:16Z

docs/admin/index.md

 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


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

docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md

matifali · 2024-11-25T10:08:44Z

docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md

+Your template can prompt the user for a repo URL with
+[parameters](../../extending-templates/parameters.md):


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

matifali · 2024-11-25T10:11:05Z

docs/images/templates/template-menu-settings.png

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

matifali

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

Co-authored-by: Ben Potter <[email protected]>

EdwardAngert · 2024-11-25T15:27:34Z

docs/admin/index.md

 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


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

EdwardAngert · 2024-11-25T15:31:40Z

docs/admin/index.md

 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


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

docs/admin/index.md

docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md

Co-authored-by: Muhammad Atif Ali <[email protected]>

EdwardAngert · 2024-11-26T19:40:11Z

@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?

matifali · 2024-11-27T07:53:00Z

@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 · 2024-11-27T18:35:56Z

(auto-)merging as a first iteration

EdwardAngert added 2 commits November 8, 2024 18:33

add definitions to admin/index

d741460

init devcontainers best practice doc

3ed5c3e

EdwardAngert added the docs Area: coder.com/docs label Nov 8, 2024

EdwardAngert requested review from bpmct and mdanter November 8, 2024 19:47

EdwardAngert self-assigned this Nov 8, 2024

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 marked this pull request as draft November 8, 2024 19:52

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

s/definition list/bullets

dcf901c

bpmct reviewed Nov 10, 2024

View reviewed changes

docs/manifest.json Outdated Show resolved Hide resolved

Merge remote-tracking branch 'origin' into bp-dev-containers

16cce07

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 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 added 9 commits November 13, 2024 14:06

admin/index glossary section

e96b1bc

when to use a dev container

22e399d

Merge remote-tracking branch 'origin' into bp-dev-containers

4f91cd0

admin/index glossary; devcontainer known issues

8e37e58

devcontainer lifecycle scripts

985233a

devcontainers directory

f2c59be

fix typo

b24f615

make fmt

4c28411

suggestions from review

fc20dc3

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 requested a review from bpmct November 20, 2024 18:05

EdwardAngert added 5 commits November 20, 2024 22:07

add steps in tabs to add-devcontainer

197cfa7

fix links; list templates

5a93ff2

make fmt + copy review addition

8e53735

fix link

80bf5da

typo fix

ca56186

link typo

de58159

EdwardAngert requested review from johnstcn November 22, 2024 20:17

adjust image size

69415d4

bpmct requested changes Nov 25, 2024

View reviewed changes

matifali reviewed Nov 25, 2024

View reviewed changes

matifali approved these changes Nov 25, 2024

View reviewed changes

Apply suggestions from code review

ae543de

Co-authored-by: Ben Potter <[email protected]>

EdwardAngert commented Nov 25, 2024

View reviewed changes

EdwardAngert and others added 3 commits November 25, 2024 10:55

Apply suggestions from code review

ca0da6d

make fmt

381bb73

close codeblock; edit starter template steps

ade54e9

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

Edward Angert and others added 5 commits November 26, 2024 19:18

code review

e46fc13

make fmt

9982af4

rename to dev containers

182d69a

2-col table

bf2e0fa

Co-authored-by: Muhammad Atif Ali <[email protected]>

make fmt

cd99937

EdwardAngert added 3 commits November 26, 2024 19:44

un-double bullet def list

d17dbea

s/devcontainer/dev container

2c3ca6d

comma typo

c28f16d

EdwardAngert requested a review from bpmct November 26, 2024 19:47

Merge remote-tracking branch 'origin' into bp-dev-containers

f344dff

EdwardAngert enabled auto-merge (squash) November 27, 2024 18:41

bpmct approved these changes Dec 2, 2024

View reviewed changes

EdwardAngert merged commit b06d833 into main Dec 2, 2024

EdwardAngert deleted the bp-dev-containers branch December 2, 2024 17:19

		Your template can prompt the user for a repo URL with
		[parameters](../../extending-templates/parameters.md):

Conversation

EdwardAngert commented Nov 8, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

bpmct left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matifali left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

EdwardAngert commented Nov 26, 2024

Uh oh!

matifali commented Nov 27, 2024

Uh oh!

EdwardAngert commented Nov 27, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

EdwardAngert commented Nov 8, 2024 •

edited

Loading

EdwardAngert commented Nov 27, 2024 •

edited

Loading