Skip to content

docs: close UX gaps found reading every doc as a first-time user #29

Description

@onelrian

Overview

A full review of the released docs found real usability gaps: several places tell a reader what to do without saying how, exactly where precision matters most, and the troubleshooting table is too generic to act on.

Intent

The real intent of this issue is:

Docs that are accurate but too vague at the exact steps a reader needs (getting a NetBird token, creating the Kubernetes Secret every install example assumes exists) are functionally as unhelpful as wrong docs, since a real user gets stuck at the same place either way.

Source of Truth

  • README.md and docs/INSTALLATION.md say "Create a NetBird personal access token" with no dashboard navigation steps.
  • README.md, docs/INSTALLATION.md, and charts/auditbridge/README.md all reference envFromSecret.NETBIRD_API_TOKEN=netbird-audit/audit-token and -e NETBIRD_API_TOKEN_FILE=/run/secrets/netbird-token as if the underlying Secret/file already exists, with no kubectl create secret command anywhere.
  • docs/SINKS.md documents generic sink variables as an abstract table with no worked example.
  • docs/OPERATIONS.md's troubleshooting table says things like "Correct credentials or connectivity" without naming what to actually check.

Tasks

  • Add exact NetBird access-token creation steps, sourced from NetBird's own docs
  • Add the missing kubectl create secret commands everywhere a Secret is referenced
  • Add a full worked example for a generic sink
  • Rewrite the troubleshooting table with real log lines and metric names to check

Acceptance Criteria

  • A first-time reader following any installation path (Docker, Compose, Kubernetes/Helm) has every command they need, nothing assumed to already exist
  • Every claim in the troubleshooting table is checked against the real log/metric strings in the code, not written from memory

Definition of Done

  • Acceptance criteria satisfied
  • cargo test/clippy/fmt and helm lint all still pass
  • No unresolved blocker remains

Metadata

Metadata

Assignees

Labels

No labels
No labels

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions