You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This reads really really well! 👏🏼 I think we could skip recommendations.md and keep it in README.md (unless it's a long section or you disagree). And for workspaces/, not sure if we'll need scheduling.md.
But again, this feedback is based on my assumption that these sections are small. Totally your call.
Thanks @jsjoeio. In my PR (#1107) I started with a simpler structure that I think works better for the current state of the project. Here's why
➖ installation/*
Since the README.md covers the current install methods in the and there is no "simple install method," I decided to remove the installation/ section altogether until the project has more install methods. Like code-server, I think there should eventually be a install script/Docker container which is the "quickstart" and then there are other methods in the installation page.
➖ quick-start.md
The README is basically the quick start at this point.
➕ about.md
A lot of projects have an overview/about explaining why a project exists and how compares to other tools. I used the following docs as a reference:
Explaining templates and workspaces together seemed to make more sense when it comes to explaining variables and why templates are required, and who manages both.
Later, I think we will need dedicated pages for both to show template/workspace features. These do not exist yet and the basics are kind of covered by the README.
➕ guides/
Similar to the Coder docs, I think we need some way to have a quickstart guide on a production VM (like code-server's)
Anyways
Here's new structure I was thinking about, would love your thoughts. I may be missing something. cc @khorne3 as well. if there any sections you'd like to add/write let me know :)
Hey @bpmct! The proposed structure looks good; I'd only suggest changing Concepts (perhaps even renaming it Core Concepts or Key Concepts for additional clarity?) and Guides, just because I think people would want to use stuff, then read in-depth articles later. Would be happy with About Coder, Concepts (Workspaces and Users and Orgs), plus possibly Guides (Using the Coder CLI). But assign me any, really, and I'll figure it out
Activity
kylecarbs commentedon Mar 29, 2022
@jsjoeio @bpmct where are we going to place the docs?
I think in
coder/codermakes sense, because this version has the tags too- similar to code-server.jsjoeio commentedon Mar 29, 2022
Agreed! @kylecarbs @bpmct What are we hoping to have in terms of docs for v2?
bpmct commentedon Apr 5, 2022
Just seeing this now. I need to fix my GitHub notifications. Let's do "a folder with markdown files."
./docsis perfect.I will discuss with Joe the best way to assign ownership and get this rolling.
bpmct commentedon Apr 7, 2022
Note to Ben and Joe - think about ways we should link to the docs from inside the product
bpmct commentedon Apr 7, 2022
Proposed structure
README.md- project description and one-liner getting startedquick-start.md- installing Coder with Docker, create first project, create first workspace (example)installation/docker.md- installing with Docker (including TLS with docker-compose + Caddy)kubernetes.md- instaling with Kubernetes (including TLS with cert-manager)linux.md- Linux Packages (deb, rpm) (including TLS with Caddy)standalone.md- Standalone binary (including TLS with Caddy)templates/README.md- what are templates in Coder, CRUD, examples linkrecommendations.md- best practices forworkspaces/README.md- what are workspaces in Coder, CRUD, config-ssh, use VS Code and JetBrainsscheduling.md- how to schedule workspaces on/offusers/bpmct commentedon Apr 7, 2022
@jsjoeio I'd love your thoughts on this 👆🏼
jsjoeio commentedon Apr 7, 2022
This reads really really well! 👏🏼 I think we could skip
recommendations.mdand keep it inREADME.md(unless it's a long section or you disagree). And forworkspaces/, not sure if we'll needscheduling.md.But again, this feedback is based on my assumption that these sections are small. Totally your call.
Let me know how else I can help!
bpmct commentedon Apr 22, 2022
Thanks @jsjoeio. In my PR (#1107) I started with a simpler structure that I think works better for the current state of the project. Here's why
➖ installation/*
Since the README.md covers the current install methods in the and there is no "simple install method," I decided to remove the
installation/section altogether until the project has more install methods. Like code-server, I think there should eventually be a install script/Docker container which is the "quickstart" and then there are other methods in the installation page.➖ quick-start.md
The README is basically the quick start at this point.
➕ about.md
A lot of projects have an overview/about explaining why a project exists and how compares to other tools. I used the following docs as a reference:
➕ concepts.md ➖ workspaces/ ➖ templates/
Explaining templates and workspaces together seemed to make more sense when it comes to explaining variables and why templates are required, and who manages both.
Later, I think we will need dedicated pages for both to show template/workspace features. These do not exist yet and the basics are kind of covered by the README.
➕ guides/
Similar to the Coder docs, I think we need some way to have a quickstart guide on a production VM (like code-server's)
Anyways
Here's new structure I was thinking about, would love your thoughts. I may be missing something. cc @khorne3 as well. if there any sections you'd like to add/write let me know :)
coder/docs/README.md
Lines 72 to 83 in 8cb6a88
khorne3 commentedon Apr 25, 2022
Hey @bpmct! The proposed structure looks good; I'd only suggest changing Concepts (perhaps even renaming it Core Concepts or Key Concepts for additional clarity?) and Guides, just because I think people would want to use stuff, then read in-depth articles later. Would be happy with About Coder, Concepts (Workspaces and Users and Orgs), plus possibly Guides (Using the Coder CLI). But assign me any, really, and I'll figure it out
bpmct commentedon Apr 25, 2022
I ended up making "workspaces" and "templates" top-level as each section got pretty long... Users and orgs isn't defined in the product yet
bpmct commentedon Apr 25, 2022
Since users/orgs are still a WIP, I think we can omit for now.