docs: rebuild Get Started around what it gets you - #7046
Merged
gustavosbarreto merged 14 commits intoSep 5, 2026
Conversation
|
Documentation preview: https://087ff04e.shellhub-docs.pages.dev |
Both pages taught a Pending tab under Devices. There is no such tab: the Devices page hides every status but accepted and forces the filter back if a URL asks for another. A reader following either page arrived at the accepted list and had nowhere to accept from. Acceptance lives in the install key now. The key's mode is what decides - automatic, manual, webhook or MAC allowlist - and a device that registered with only a tenant ID falls to the namespace's default key. What waits for a person waits in that key's activity, which is what the pages point at. The four modes are worth stating together, because choosing between them before a fleet arrives is the actual decision; deciding device by device is the fallback, not the plan.
Accepting Devices was a second home for facts that already had one. Install Keys covers the modes, the tags, the ephemeral flag and the review; Managing Devices covers the statuses and what removing does. The page restated all of it and left a reader deciding which of the two to believe. It is gone, and the two things only it said moved to the pages that own them: what to look at before accepting goes to the key's review section, alongside the picture of it; rejected keeping the record goes beside removing, which it belongs next to. The onboarding guide taught the wrong path outright. Its first step is a plain install with nothing handed to the agent, which pairs: the installer prints a code and waits. The second step then walked the reader to an install key's activity, which is where a fleet is reviewed and not where that code is answered. It now shows what the terminal prints and the screen the link opens.
The guide opened with a command and no account of where it comes from. In the product you do not type it: Add Device asks whether this is one machine or a fleet, asks how to install, and builds it. The step now starts there, with a picture of it, and the command follows.
It promised the short path from nothing and opened on a console screen, which needs an account and a namespace the page never mentioned. Sign-up on Cloud creates the account and not the namespace - the console holds you on a create-namespace screen until it has one - and self-hosting creates both at once on the setup screen. Being invited is a third path, and lands you in someone else's namespace with nothing to create. A step zero says which of the three you are in. The install step also handed out the fleet command, which enrols through an install key and never prints the code the next step is about. It points at that path instead of teaching it. The connect step carried the browser terminal, a native client, and the whole login-approval story. The first two are the step; approval is a sentence and a link to the page that owns it. The self-hosting quickstart ended by repeating all of this, one address apart. It now hands over.
Step zero told all three at once, in a row of paragraphs, and every reader had to walk past two that were not theirs. They are alternatives, so they go in tabs: pick where you are and read one. Cloud gets a picture of the screen the console holds you on until you name a namespace, which is the part of signing up nobody expects and the reason this step exists at all. Every panel is in the HTML and the script hides the ones not selected. Hiding them server-side would lose them to a reader who never runs it, including the one indexing the page.
Three steps named after mechanics - install, accept, connect - and a list of links for everything after. A reader finishing it had one device and no idea whether the product was done teaching them. It is two things instead, named for what they achieve. Reaching a device is the first, broken into the four things you actually do, one picture each. Sharing it is the second, and it was not in the guide at all: it lived in two reference pages a reader had to know to look for, and it is half of why anyone runs this rather than sshd. That second one carries the fact that surprises people, which is that membership grants nothing - a new member signs in and reaches no device until a policy says so. Every subsection is numbered actions rather than prose, so the page can be followed with a terminal open beside it instead of read.
The guide was written for both deployments at once, which cost a tab on the account section and a caveat on every address. It now says which one it covers and hands the other case to the quickstart before the reader starts. The connect step also skipped the part people actually get stuck on. Two separate things let that first terminal open: a starter policy the namespace is born with, granting the owner everything, and an identity the browser enrols on the spot - which it can only do because the console session already says who you are. An SSH client has no such session, so it offers a key and the login parks for approval. The step now says both, and names them, so the section after it is not introducing default-deny out of nowhere.
Three names were in play for one idea - a section called Get Started, a page called Onboarding Guide inside it, and a Self-Hosting Quickstart elsewhere - so a reader could not tell whether they were alternatives or stages. There are two of these and they differ by deployment, so they are Quickstart and Self-Hosting Quickstart. The section keeps its name; the page inside it says what it is. The SSH step also carried a picture of the device page to copy an address from. The device list has the same address and the same copy button, and the reader is already looking at it.
A group could only open. Anything introducing what was under it had to be a child pretending to be an overview - Install the Agent held Choosing a Method, so the heading a reader clicks did nothing and the page that explains the group sat inside it, indistinguishable from the platforms it introduces. A heading with an href renders as two controls rather than one: the label goes to its page, the chevron opens the group. Wrapping either in the other makes one control that has to guess which was meant. Flattening yields such a group before its children, so previous/next walks into the overview and then through what it introduces, which is the order it reads in.
It was named for a decision - Choosing a Method - and read as a footnote about auto-detection, while the ten pages it introduces were reachable only by opening a group in the sidebar. A reader who wanted Yocto had to guess it was in there. The platforms are on the page now, split by whether the installer can reach the machine at all: five it picks between, and five that are a different route on - an image build, a ports tree, a source build.
The install page opened on a pipe-to-shell, which is the answer for a machine you already have a terminal on and not for a reader arriving to install something. The hosted installer is a link, and it now looks like the thing to click - the design system's primary button, in the plain CSS this app is written in. The command it replaced is what that page hands you anyway, so keeping it here was showing the reader the destination before sending them to it. One per page, deliberately: two of these and the page has neither.
Install instructions held no instructions. It was a list of links under a heading claiming otherwise, followed by a detection order and an INSTALL_METHOD override that the hosted installer decides for you anyway, and a table of installer variables the same screen already collects. What is left is what only this page can say: which platforms exist, and which of them the installer cannot reach. Building into an image was a section of its own and belongs to the three entries it is about, so it sits under them.
Ten pages sat under Install the Agent, and half of them are not an install at all: an OpenEmbedded layer, a Buildroot tree, a ports tree, a source build. Grouping them by the page that introduces one-liners implied the one-liner reaches them. They are their own group in the sidebar now. The installer page still introduces them, with what they have in common and the image-build caveats that only apply to them, so the group needs no overview of its own. URLs are unchanged: /get-started/install/<platform> is still where each lives, and it is still true of every one of them.
A hundred lines, and one of them was not already written somewhere else. Pairing and its accept screen are the quickstart's second step; the shellhub-agent wrapper is on the install page; install keys have a page of their own covering modes, tags and the deprecated tenant-only path; the status table was duplicated verbatim from Managing Devices. What only it had was the comparison - what the agent is given, where the device lands, what each is for - and that is a fleet question rather than a first-day one. It moves to Managing Devices, which already answers what a device is, what its statuses mean and what identifies it, and was missing only how one arrives. Twelve links pointed at it. The ones that finish an install and ask what now go to the quickstart, which is the walkthrough they meant; the ones asking which credential does what go to the comparison.
gustavosbarreto
force-pushed
the
docs/access-control-shots
branch
from
September 5, 2026 16:11
45cdcfb to
1e2916a
Compare
gustavosbarreto
force-pushed
the
docs/get-started-rework
branch
from
September 5, 2026 16:11
b842c51 to
cb1ccdc
Compare
|
Documentation preview: https://55b4f16c.shellhub-docs.pages.dev |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Reshapes the Get Started section: one guide that goes from no account to a
colleague reaching your device, and two reference pages behind it. Two pages are
dissolved into the ones that already owned their content.
Why
The section held four pages of three different kinds presented as a sequence — a
tutorial, a page of installer trivia, an explanation of enrolment, and a table of
environment variables — and the tutorial began on a console screen, which needs
an account and a namespace it never mentioned.
Two of those pages were mostly duplicates.
accepting.mdxrestated the installkey page;
enrolling-devices.mdxrestated the quickstart, the install key pageand the device status table, verbatim.
The onboarding guide also taught a Pending tab that no longer exists: the Devices
page hides every status but accepted (
pages/devices/index.tsx:134) and forcesthe filter back (
:140-144). Acceptance lives in the install key's activity now.Opened #7043 for the Dashboard card still pointing at that URL.
Changes
each a few numbered actions with one picture. It now starts at the account —
signing up, self-hosting, or being invited, in tabs — and ends with a colleague
connecting, which was in no guide at all. It says which deployment it covers.
two separate things people conflate — the starter Owner access policy
(
pkg/models/access-policy.go:80-91), and the identity the browser enrols onthe spot because the console session already says who you are
(
ConnectDrawer.tsx:236). An SSH client has neither, so its first login parksfor approval.
and it lists the platforms it introduces instead of hiding them in the sidebar.
The detection order and the installer variable table are gone — the hosted
installer collects those.
systems, not the installer with another flag.
accepting.mdxandenrolling-devices.mdx. The one thing onlythe latter had — the comparison of what the agent is given and where the device
lands — moved to Managing Devices, which answers every other question about a
device and was missing only how one arrives.
TabsandActionLink: two components the docs app did not have. Everytab panel is in the HTML and the script hides the unselected ones, so a reader
who never runs it still gets the content.
hrefanditemsrenders as a link plus atoggle, so a group heading can be the overview of what it contains.