From dc8a9c7a08478febb647da5b9c5b9a503345a7c9 Mon Sep 17 00:00:00 2001 From: andrewfulton9 Date: Thu, 25 Jun 2026 10:14:33 -0600 Subject: [PATCH 1/2] initial pass --- docs/docs/references/personas.md | 49 ++++++++++++++++++++++++++++++++ docs/sidebars.js | 2 +- 2 files changed, 50 insertions(+), 1 deletion(-) create mode 100644 docs/docs/references/personas.md diff --git a/docs/docs/references/personas.md b/docs/docs/references/personas.md new file mode 100644 index 00000000..f8e6f61f --- /dev/null +++ b/docs/docs/references/personas.md @@ -0,0 +1,49 @@ +# Personas + +Nebari Kubernetes Platform (NKP) is designed around three primary roles. Understanding these roles clarifies who is responsible for each layer of the platform and what each group needs from the documentation. + +--- + +## Platform admin + +**Who they are:** Infrastructure engineers, DevOps practitioners, or IT administrators responsible for standing up and maintaining the platform. They are comfortable with Kubernetes, cloud providers, and infrastructure-as-code tooling such as OpenTofu or Terraform. They may work within a central platform team or provide services to multiple internal teams. + +**What they do:** + +- Provision clusters across cloud providers (AWS, GCP, Azure, Hetzner) or on-premises using the `nic` CLI +- Manage the foundational services bundled with every deployment: identity (Keycloak), API gateway (Envoy), observability, and GitOps (ArgoCD) +- Install, update, and remove software packs to extend the platform's capabilities +- Control user access, quotas, and security policies +- Monitor cluster health, costs, and resource utilization + +**What they need from the docs:** Step-by-step deployment guides, configuration reference for the `nic` CLI and its YAML schema, upgrade and migration procedures, troubleshooting guides for infrastructure-level issues, and clear explanations of how packs integrate with the foundational services. + +--- + +## Pack developer + +**Who they are:** Software engineers or platform specialists who build and publish reusable capabilities for the platform. They understand Kubernetes custom resources, Helm charts, and how the Nebari Operator works. They may be internal to an organization building proprietary tooling, or open-source contributors publishing packs for the broader community. + +**What they do:** + +- Author `NebariApp` custom resources that define a software pack's components, dependencies, and configuration +- Package tools (notebook environments, model serving, experiment tracking, dashboards) so they integrate automatically with SSO, TLS, routing, and telemetry +- Test packs against different cluster configurations and platform versions +- Publish packs to a registry for platform admins to discover and install + +**What they need from the docs:** The `NebariApp` CRD specification, the operator's reconciliation model, integration contracts for SSO and routing, pack authoring guides, and versioning and publishing conventions. + +--- + +## End user + +**Who they are:** Data scientists, ML engineers, researchers, and analysts who use the tools and environments the platform provides. They are proficient in Python or R and work daily with Jupyter notebooks, ML frameworks, and data pipelines. They are generally not responsible for infrastructure and expect the platform to simply work. + +**What they do:** + +- Log in through the platform landing page and launch notebook environments or other deployed tools +- Run experiments, train models, and analyze data using pre-configured environments +- Collaborate with colleagues by sharing notebooks, dashboards, and results +- Scale computation to cluster resources without managing infrastructure themselves + +**What they need from the docs:** Getting-started guides for their specific tools (JupyterHub, VS Code, Argo Workflows, etc.), how to request access or additional resources, and troubleshooting guides for common environment issues. diff --git a/docs/sidebars.js b/docs/sidebars.js index 6be21d5b..c2abff62 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -68,7 +68,7 @@ module.exports = { label: "References", link: { type: "doc", id: "references/index" }, items: [ - // Add reference docs here + "references/personas", ], }, { From 5c5b4fe40f860e26a704db0f2d34935caf64414d Mon Sep 17 00:00:00 2001 From: andrewfulton9 Date: Thu, 25 Jun 2026 10:22:47 -0600 Subject: [PATCH 2/2] improvements --- docs/docs/references/personas.md | 43 ++++++++++++++++++++++++++------ 1 file changed, 36 insertions(+), 7 deletions(-) diff --git a/docs/docs/references/personas.md b/docs/docs/references/personas.md index f8e6f61f..8050194d 100644 --- a/docs/docs/references/personas.md +++ b/docs/docs/references/personas.md @@ -1,12 +1,16 @@ # Personas -Nebari Kubernetes Platform (NKP) is designed around three primary roles. Understanding these roles clarifies who is responsible for each layer of the platform and what each group needs from the documentation. +Nebari Kubernetes Platform (NKP) is designed around three primary roles. Understanding these roles clarifies who is responsible for each layer of the platform and what each group needs to be successful. --- ## Platform admin -**Who they are:** Infrastructure engineers, DevOps practitioners, or IT administrators responsible for standing up and maintaining the platform. They are comfortable with Kubernetes, cloud providers, and infrastructure-as-code tooling such as OpenTofu or Terraform. They may work within a central platform team or provide services to multiple internal teams. +**Who they are:** + +- Infrastructure engineers, DevOps practitioners, or IT administrators responsible for standing up and maintaining the platform +- Comfortable with Kubernetes, cloud providers, and infrastructure-as-code tooling such as OpenTofu or Terraform +- May work within a central platform team or provide services to multiple internal teams **What they do:** @@ -16,13 +20,23 @@ Nebari Kubernetes Platform (NKP) is designed around three primary roles. Underst - Control user access, quotas, and security policies - Monitor cluster health, costs, and resource utilization -**What they need from the docs:** Step-by-step deployment guides, configuration reference for the `nic` CLI and its YAML schema, upgrade and migration procedures, troubleshooting guides for infrastructure-level issues, and clear explanations of how packs integrate with the foundational services. +**What they need:** + +- Declarative, repeatable tooling that abstracts cloud provider differences +- Reliable upgrade paths with minimal manual intervention +- Clear visibility into cluster health, resource consumption, and costs +- Fine-grained access controls and policy enforcement +- The ability to integrate packs with foundational services such as SSO, routing, and observability without manual configuration --- ## Pack developer -**Who they are:** Software engineers or platform specialists who build and publish reusable capabilities for the platform. They understand Kubernetes custom resources, Helm charts, and how the Nebari Operator works. They may be internal to an organization building proprietary tooling, or open-source contributors publishing packs for the broader community. +**Who they are:** + +- Software engineers or platform specialists who build and publish reusable capabilities for the platform +- Familiar with Kubernetes custom resources, Helm charts, and how the Nebari Operator works +- May be internal to an organization building proprietary tooling, or open-source contributors publishing packs for the broader community **What they do:** @@ -31,13 +45,22 @@ Nebari Kubernetes Platform (NKP) is designed around three primary roles. Underst - Test packs against different cluster configurations and platform versions - Publish packs to a registry for platform admins to discover and install -**What they need from the docs:** The `NebariApp` CRD specification, the operator's reconciliation model, integration contracts for SSO and routing, pack authoring guides, and versioning and publishing conventions. +**What they need:** + +- Well-defined contracts for how packs integrate with the platform's SSO, routing, TLS, and telemetry layers +- A reliable operator reconciliation model they can test against +- Clear versioning and compatibility guarantees +- A publishing mechanism that makes packs discoverable and installable without requiring platform admin intervention in the development loop --- ## End user -**Who they are:** Data scientists, ML engineers, researchers, and analysts who use the tools and environments the platform provides. They are proficient in Python or R and work daily with Jupyter notebooks, ML frameworks, and data pipelines. They are generally not responsible for infrastructure and expect the platform to simply work. +**Who they are:** + +- Data scientists, ML engineers, researchers, and analysts who use the tools and environments the platform provides +- Proficient in Python or R, working daily with Jupyter notebooks, ML frameworks, and data pipelines +- Generally not responsible for infrastructure and expect the platform to simply work **What they do:** @@ -46,4 +69,10 @@ Nebari Kubernetes Platform (NKP) is designed around three primary roles. Underst - Collaborate with colleagues by sharing notebooks, dashboards, and results - Scale computation to cluster resources without managing infrastructure themselves -**What they need from the docs:** Getting-started guides for their specific tools (JupyterHub, VS Code, Argo Workflows, etc.), how to request access or additional resources, and troubleshooting guides for common environment issues. +**What they need:** + +- Immediate access to pre-configured, stable environments without installation friction +- Scalable compute that can be requested on demand without involving infrastructure teams +- Reliable collaboration and sharing mechanisms +- Reproducible environments across sessions and teammates +- Clear paths to escalate when something isn't working