Best Practices Docs #311
Best Practices Docs #311
Conversation
Review or Edit in CodeSandboxOpen the branch in Web Editor • VS Code • Insiders |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Review or Edit in CodeSandboxOpen the branch in Web Editor • VS Code • Insiders |
| }, | ||
| "sdk": { | ||
| "title": "SDK", | ||
| "title": "SDK v3", |
There was a problem hiding this comment.
Good choice on the location
| ## Use Cases | ||
|
|
||
| 3. Install the SDK: | ||
| CodeSandbox SDK has been designed to help you build and launch any projects that require: |
There was a problem hiding this comment.
| CodeSandbox SDK has been designed to help you build and launch any projects that require: | |
| CodeSandbox SDK is designed to help you build and launch any projects that require: |
|
|
||
| ## Architecture Overview | ||
|
|
||
| At its heart, the SDK enables management of and connections to Sandboxes. You have a lot of flexibility on how you want to deliver secure, scalable development environments: |
There was a problem hiding this comment.
| At its heart, the SDK enables management of and connections to Sandboxes. You have a lot of flexibility on how you want to deliver secure, scalable development environments: | |
| The SDK enables management of and connections to Sandboxes in secure and scalable development environments. Due to the design of the architecture, there are many options for how to expose functionality in your application. |
There was a problem hiding this comment.
@christianalfoni Can you add a section above this graphic explaining the architecture?
The image is very helpful, but the page still needs a section that describes the architecture in words.
|
|
||
|  | ||
|
|
||
| ## Environment Types |
There was a problem hiding this comment.
What is an environment? And why do they matter?
We should explain what we mean by environments before identifying the types.
|
|
||
| ## The Development Environment Lifecycle | ||
|
|
||
| Understanding how your created environments move through their lifecycle is crucial for effective integration. You are building a product with end users that will see these environments through the lens of them being their own _project_. This project will have at least one Sandbox assigned to it for the end user to interact with. Whether that be directly or through an agent. This diagram touches on the integration points through the lifecycle of a project (SDK) VS a Sandbox. |
There was a problem hiding this comment.
| Understanding how your created environments move through their lifecycle is crucial for effective integration. You are building a product with end users that will see these environments through the lens of them being their own _project_. This project will have at least one Sandbox assigned to it for the end user to interact with. Whether that be directly or through an agent. This diagram touches on the integration points through the lifecycle of a project (SDK) VS a Sandbox. | |
| Understanding how sandboxes and templates progress through a development lifecycle is key to integrating CodeSandbox effectively. | |
| An end user may interact with a Sandbox directly, or indirectly through an agent (such as a connected service or automated workflow). Depending on the development flow that you are creating, you will need to mindful of when to fork from a template and when to restart sandboxes. | |
| The diagram below illustrates how the SDK and Sandboxes interact throughout a development lifecycle. |
There was a problem hiding this comment.
We should also link to /manage-sandboxes to learn more
|
|
||
| Use these methods for: | ||
|
|
||
| - **Validation** - Cross-check your internal state against actual sandbox status |
There was a problem hiding this comment.
Where can I learn how to do this?
| Use these methods for: | ||
|
|
||
| - **Validation** - Cross-check your internal state against actual sandbox status | ||
| - **Administrative features** - Build dashboards and debugging tools |
There was a problem hiding this comment.
I don't know how I feel about adding this to the docs. Unless we have tools we provide for them to use, all we are saying is "build your own observability layer bc we don't have one for you"
|
|
||
| - **Validation** - Cross-check your internal state against actual sandbox status | ||
| - **Administrative features** - Build dashboards and debugging tools | ||
| - **Runtime information** - Get current resource usage and activity data |
There was a problem hiding this comment.
What are you trying to say here?
Suggestion
Monitor usage and runtime data - Leverage [data from the CLI](link to page) to monitor usage and activity data
| - **Validation** - Cross-check your internal state against actual sandbox status | ||
| - **Administrative features** - Build dashboards and debugging tools | ||
| - **Runtime information** - Get current resource usage and activity data | ||
| - **Troubleshooting** - Investigate sandbox issues or unexpected states |
There was a problem hiding this comment.
This is too vague to be helpful. Do we have guidance that we can point them to?
|
|
||
| # VM Specs | ||
|
|
||
| <Callout type="warning" emoji="⚡"> |
There was a problem hiding this comment.
Can we move this out of the callout and into a section with a header at the bottom titled '# Best Practices'?
|
I took a first pass the the docs The integration guideIt's a great idea for a page, but the bullet points that are listed now are devoid of context, vague and missing actionable details. I've left some comments on what improvements could look like, but I think the page needs a full refresh. CLI docsWe need better docs for the CLI - We can take inspiration from docker for how to format this.
Missing troubleshooting and FAQsWe need to update the FAQs to include the items we posted in here Add a versions & Changelog pageIt's nice to see the callout in the intro page, but we need the SDK versions to be more discoverable |
WIP