Skip to content
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

☂️ Restructure our docs #13434

Closed
bpmct opened this issue Jun 1, 2024 · 22 comments · Fixed by #14421 · May be fixed by grepdemos/coder#14
Closed

☂️ Restructure our docs #13434

bpmct opened this issue Jun 1, 2024 · 22 comments · Fixed by #14421 · May be fixed by grepdemos/coder#14
Assignees
@matifali @EdwardAngert @bpmct @stirby
Labels
docs Area: coder.com/docs ☂️ epic An issue of issues

Comments

@bpmct
Copy link
Member

bpmct commented Jun 1, 2024 •
edited by matifali
Loading

We're working on a new information hierarchy for coder.com/docs with a few goals in mind:

  1. Quickstart: Our current structure reads like a reference, which can be great for recalling information but makes it difficult for a new reader who is unfamiliar with Coder (or CDEs) to learn the basics, even by deploying.
  2. Developer Guides: Clear hub for for end users on interacting with Coder including creating workspaces, connecting, scheduling, and personalizing
  3. Administration Hub: The Administration page should serve as a clear path to administering Coder, including tutorials with best practices, docs on administrative features, and reference architectures and use cases.

You can see our progress in the restructure-new branch or even on our docs site: https://coder.com/docs/@restructure-new

Coder.com Changes Required

  • Fix our search weights
  • Add autogenerated og:image for each page
  • Improve loading speed
  • Move sidebar to the top right
  • Change URL structure
  • Add support for sub icons
  • Add border around images for better contrast between Coder dashboard screenshots and background
  • Design a landing page for the home page that links to the various sections

Docs

  • About
  • Getting Started
    • Landing Page
    • Coder Tour
      • Coder installation on docker
      • Configuring the first template
      • Creating and connecting to a workspace
      • Template modification
    • Screenshots
  • Install
    • Landing Page
      • Reduction of clutter from previous landing
      • Tabs and children nesting
    • Coder CLI
    • Docker
    • Kubernetes
      • Migrate auto versioning
      • Correct CLI flags with new PR method
    • OpenShift
    • Other Cloud Providers
    • Unofficial Methods
      • EC2
      • GCP compute engine
      • Azure
      • Any other
    • Post-installation steps (part of control plane configuration)
      • Reverse proxy (Setup SSL certs)
      • Docker socket permission (explain for k8s, docker-compose and system-service) installations
  • User guides
    • Landing Page
    • Access Workspaces
    • Workspace Scheduling
    • Dotfiles
      • From a template
      • Personalize script
  • Administration
    • Control plane access (previously admin/configure.md)
      • Add external auth
    • Infrastructure
      • Landing Page
      • Architecture Diagram
      • Validated Architectures (from @ericpaulsen + 1000-3000 user scale test)
      • Scale Testing
      • Scale Testing Utilities
    • User Management (Does this replace the existing admin/auth page)
    • Templates
      • Landing Page
      • Creating Templates
      • Managing Templates
        • Image management
        • Devcontainers(envbuilder)
        • Change management
      • Extending Templates
        • Landing Page
          • Agents
            • Multiple Agents
          • Resource Persistence
          • Variables
          • Parameters
          • Resource Metadata
          • Agent Metadata
          • Ordering
        • Web IDEs
        • External Authentication
      • Template Permissions
        • Add template policies
      • Create corresponding tutorials
      • Troubleshooting Templates
      • Protecting Resources
    • Provisioners
    • Notifications
    • Integrations
      • Landing page
        • Add links to children pages via landing page (ideally via a widget)
      • Prometheus
      • coder-logstream-kube
      • Additional Kubernetes clusters
      • JFrog (Artifactory and XRay)
      • Hashicorp Vault
      • Island
    • Workspaces
      • Landing Page
        • Bulk operations
        • Management and filtering
        • Update policies stub
      • Workspace Lifecycle
      • Dormancy Cleanup
      • Workspace-level scheduling
      • Workspace Tags
    • Networking
      • Port forwarding
      • STUN & NAT
      • Decision on Networking Performance Doc
        Waiting until merge to add more performance benchmarking, blog post mention is sufficient
    • Monitoring
      • Logs
      • Metrics
      • Observibility Dashboard
      • Support Bundle
      • Health Check
        • Add screenshot
    • Security
      • Audit logs
      • Secrets
      • Security disclosures
    • Tutorials
      • Copy everything from tutorials in guides/
      • Add VM support for offline docs or mention that the guide is K8s only
    • FAQ
      • We want to keep this since we frequently link, or move it over
    • Docs to consider
  • Reference
    • Landing Page
    • CLI
    • API

Chores

  • Ensure make gen writes to the new docs locations
    • CLI
    • REST API
    • Prometheus Metrics
    • Version rewrites
    • Audit logs
  • Check for (and address) any TODOs
  • Ensure that all sections either have A) icon for each sub page or B) no icons for the section
  • Check for (and address) any broken images
  • Add redirects from old URLs to new docs pages/sections with over 5 views per month
  • Modify in-product docs links to link to the new location as well
  • Check for broken links
  • Switch link checker to https://github.com/UmbrellaDocs/action-linkspector
  • https://github.com/coder/coder.com/issues/508
    • "Recent updates" gallery
    • Main hero element
    • Ecosystem gallery
  • Migrate updates to main into restructure branch
    • Workspace tags
    • Releases calendar
@coder-labeler coder-labeler bot added ☂️ epic An issue of issues docs Area: coder.com/docs labels Jun 1, 2024
@bpmct bpmct assigned bpmct and unassigned bpmct Jun 1, 2024
@matifali
Copy link
Member

matifali commented Jun 2, 2024

The new docs look way cleaner. 🚀

@matifali
Copy link
Member

matifali commented Jun 4, 2024 •
edited
Loading

Good time to migrate docs link checker to https://github.com/UmbrellaDocs/action-linkspector
The current one is going to be deprecated in favor of this.

@bpmct
Copy link
Member Author

bpmct commented Jun 15, 2024

Added validated architectures @ericpaulsen https://coder.com/docs/@restructure/admin/infrastructure/validated-architectures

@bpmct
Copy link
Member Author

bpmct commented Jun 15, 2024

@stirby what is your rationale about "screenshots" being in getting started? I added it there, but I figured that section would be tutorial oriented. Overall, I'm a bit confused on the difference between about and getting started sections

@stirby
Copy link
Collaborator

stirby commented Jun 17, 2024

In my eyes, "Getting Started" should be day-zero setup process for those already interested in the product. "About" should be seen by anyone exploring the product, regardless of setup interest.

I put it under "Getting Started" since I see myself "touring" the product by looking around the UI, then setting it up.

I assume you'd suggest moving it under "About?" I agree it conceptually fits but I wanted to avoid a subsection there.

@stirby
Copy link
Collaborator

stirby commented Jun 17, 2024

Nevermind, open to moving screenshots under about. We could also add a changelog or similarly high-level docs under there later.

@bpmct
Copy link
Member Author

bpmct commented Jun 23, 2024 •
edited
Loading

I'm kind of stuck on where to put Provisioners. I put it under Admin, but it doesn't feel right... Maybe under Admin->Infrastructure or Admin->Templates?

@matifali
Copy link
Member

I would go with infrastructure but will link from groups as it's more useable with groups/teams managing their own compute resources.

@matifali matifali mentioned this issue Jun 28, 2024
Merged
@stirby
Copy link
Collaborator

stirby commented Jul 19, 2024

Seems like we may need a deployment/ section under administration.

  • configure.md
  • Upgrading deployments
  • Provisioners

Not sure what the README would look like, maybe talking about scope?

Not a concrete decision, just something to investigate.

@matifali
Copy link
Member

We may also document the secret management methods we support at https://coder.com/docs/secrets.

@stirby
Copy link
Collaborator

stirby commented Jul 22, 2024

@matifali good call! I think these belong in "integrations" but we should link to them in the secrets doc as children.

@matifali matifali mentioned this issue Aug 6, 2024
Closed
@matifali
Copy link
Member

matifali commented Aug 6, 2024 •
edited
Loading

We may also document the secret management methods we support at coder.com/docs/secrets.

This is now complete. I added this under integrations and linked from admin/security/secrets.
https://github.com/coder/coder/blob/restructure/docs/admin/security/secrets.md#secrets-management

@matifali matifali mentioned this issue Aug 12, 2024
Merged
@stirby
Copy link
Collaborator

stirby commented Aug 14, 2024 •
edited by matifali
Loading

For the rest of this week:

@stirby

  • RDP Page fixes
  • Migrate Scale pages to infrastructure
  • Merging Landing Page

@matifali

  • External Authentication ✅ (Moved this to Control plane configuration)
  • Image Management ✅
    • Mentioning Envbuilder, devcontainer spec, envbuilder templates
  • Security ✅
  • Final tutorials ✅

@matifali matifali assigned matifali and stirby and unassigned bpmct Aug 15, 2024
@matifali matifali mentioned this issue Aug 21, 2024
Merged
@stirby
Copy link
Collaborator

stirby commented Aug 22, 2024 •
edited
Loading

Atif Tasks

  • Template Management ✅
    • Copy Change Management under template management ✅
    • Copy Devcontainers file ✅
    • Change "Creating Templates" tabs, rename "Git" to "CI/CD" ✅
  • Extending templates: add terraform modules ✅
  • Separate IDEs between user guides and ✅
  • Add Post-installation steps

Stephen Tasks

  • Correct Templates page hierarchy
  • Add metrics page
  • Decision on security disclosures

This was referenced Aug 23, 2024
Merged
Merged
@stirby
Copy link
Collaborator

stirby commented Sep 10, 2024 •
edited
Loading

Tasks

Atif

  • Move "Getting Started" to "About" remove old "About" content
  • Move "Screenshots" under home
  • Move "Tour Coder" under Home
  • Rename "Control Plane" to "setup"
  • Move "Automation" to "Reference"
  • External Authentication under Administration
  • Add icons for all second-level headings

Stephen

  • Write Landing Pages
    • User guides
    • Administration
    • Security
  • Metrics Page
  • Move Notifications to Monitoring
  • Icons for User guides

@stirby
Copy link
Collaborator

stirby commented Sep 11, 2024 •
edited
Loading

Steve's task for 09/11 -> 09/14

  • Add premium badges for new pricing plan
  • likely deprecate enterprise badges
  • Pricing disambiguation page

@stirby
Copy link
Collaborator

stirby commented Sep 13, 2024

#14673

@stirby
Copy link
Collaborator

stirby commented Sep 17, 2024 •
edited
Loading

Completed Tasks

Changes to main

Stephen Tasks

Edward / Atif:

@stirby
Copy link
Collaborator

stirby commented Sep 17, 2024

We're waiting to return the enterprise feature comparison until we add the coderd licensing options. Then we'll have a "Licensing" section under administration.

  • Licensing
    • README.md : Explains how to add licenses, license limit
    • compare.md : Feature set comparison between OS / Premium

@lizard-boy lizard-boy mentioned this issue Sep 18, 2024
Open
@bpmct
Copy link
Member Author

bpmct commented Sep 23, 2024

I'll do the licensing stuff this week. What is an ETA looking like, including us adding redirects?

@matifali
Copy link
Member

Adding redirects requires fixing all dead links and stale images and checking for missing docs. If we can get these completed by end of the week we can add redirects and merge.

@bpmct
Copy link
Member Author

bpmct commented Sep 25, 2024

Added this checkbox to the tracker above:

  • Modify in-product docs links to link to the new location as well

@EdwardAngert EdwardAngert reopened this Sep 27, 2024
@stirby stirby closed this as completed in 419eba5 Oct 5, 2024
@matifali matifali mentioned this issue Jan 31, 2025
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@matifali matifali

@EdwardAngert EdwardAngert

@bpmct bpmct

@stirby stirby

Labels
docs Area: coder.com/docs ☂️ epic An issue of issues
Projects
None yet
Milestone
No milestone
4 participants
@matifali @EdwardAngert @bpmct @stirby