Skip to content

☂️ Restructure our docs #13434

Closed
grepdemos/coder
#14
@bpmct

Description

@bpmct

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

Metadata

Metadata

Labels

☂️ epicAn issue of issuesdocsArea: coder.com/docs

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions