Skip to content

V2 Docs  #657

Closed
Closed

Description

@misskniss

As a user, I want really great concise docs for the product so I can understand how to use and devlop with the product.

Activity

  1. added this to the V2 Beta milestone on Mar 29, 2022
  2. kylecarbs commented on Mar 29, 2022

    @kylecarbs
    Member

    @jsjoeio @bpmct where are we going to place the docs?

    I think in coder/coder makes sense, because this version has the tags too- similar to code-server.

  3. jsjoeio commented on Mar 29, 2022

    @jsjoeio
    Contributor

    Agreed! @kylecarbs @bpmct What are we hoping to have in terms of docs for v2?

    • a folder with markdown files
    • a website
    • something else?
  4. bpmct commented on Apr 5, 2022

    @bpmct
    Member

    Just seeing this now. I need to fix my GitHub notifications. Let's do "a folder with markdown files." ./docs is perfect.

    I will discuss with Joe the best way to assign ownership and get this rolling.

  5. bpmct commented on Apr 7, 2022

    @bpmct
    Member

    Note to Ben and Joe - think about ways we should link to the docs from inside the product

  6. bpmct commented on Apr 7, 2022

    @bpmct
    Member

    Proposed structure

    • README.md - project description and one-liner getting started
    • quick-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 link
      • recommendations.md - best practices for
    • workspaces/
      • README.md - what are workspaces in Coder, CRUD, config-ssh, use VS Code and JetBrains
      • scheduling.md - how to schedule workspaces on/off
    • users/
      • TBD
  7. bpmct commented on Apr 7, 2022

    @bpmct
    Member

    @jsjoeio I'd love your thoughts on this 👆🏼

  8. jsjoeio commented on Apr 7, 2022

    @jsjoeio
    Contributor

    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.

    Let me know how else I can help!

  9. bpmct commented on Apr 22, 2022

    @bpmct
    Member

    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

    - [About Coder](./about.md#about-coder)
    - [Why remote development](about.md#why-remote-development)
    - [Why Coder](about.md#why-coder)
    - [What Coder is not](about.md#what-coder-is-not)
    - Concepts
    - Templates
    - Workspaces
    - Users and Organizations
    - Guides
    - Using the Coder CLI
    - Install Coder on a VM with Caddy + LetsEncrypt
    - Building templates in Coder

  10. khorne3 commented on Apr 25, 2022

    @khorne3
    Contributor

    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

  11. bpmct commented on Apr 25, 2022

    @bpmct
    Member

    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

  12. bpmct commented on Apr 25, 2022

    @bpmct
    Member

    Since users/orgs are still a WIP, I think we can omit for now.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

docsArea: coder.com/docs

Type

No type

Projects

No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions