Clarity in enterprise setup documentation and UI

[TrainCo]

Select Topic Area

Product Feedback

Body

Hi GitHub Team,
I recently attempted to set up a GitHub Enterprise trial and found the process extremely confusing and frustrating. I’m not an influencer or industry expert. I am just a regular user trying to do something that should be simple: convert my personal account into an enterprise setup.

Here’s the core issue:

You cannot convert your personal account directly into an enterprise account. You must create an enterprise account and then create or transfer organizations under it.

This one sentence cleared up hours of confusion for me. Unfortunately, this clarity is missing from your documentation and UI. Instead, users are left to decipher GitHub-specific terminology like “enterprise account,” “organization,” “account owner,” and “managed users,” often without context or guidance. In addition, the UI gives user an explicit "Transform your user into an organization" page which is unnecessarily counterintuitive because "This user will become an organization and can't be an owner.". Wait, what? Then why does this page even exist? The process is not possible following the assumptions posed on this page.

Some ideas that would help:

• The above bolded statement verbatim somewhere easily found (like the UI or in bold on page 1 of the Enterprise account setup pages)
• A clear, upfront explanation of the relationship between personal accounts, organizations, and enterprise accounts.
• A step-by-step guide that avoids jargon and focuses on real-world use cases (i.e. “I want to manage my team under an enterprise trial”).
• Better error messages when users try to use their personal account name for an organization or enterprise.
• Error messages that link to documentation related to the error (as long as the documentation is comprehensible and does not contain 200 terms the need specific GitHub-only definitions).
• A visual diagram showing how these entities relate to each other.

I’m sharing this because I believe GitHub is a great platform, and I want others to avoid the same frustration. Please consider simplifying this part of the onboarding experience because it would make a huge difference. At least to me and some of my coworkers.

My issue has been resolved. I am posting this in hope that it will save others from the frustration I recently experienced.

[Nzko-cyber]

Put the bolded statement up front
On both the Enterprise Account Setup documentation and the “Transform into an organization” UI.

Clarify relationships between entities
Explain in plain language:

Personal account = for individuals

Organization = container for repos, teams, permissions

Enterprise account = container for organizations, billing, policies

Managed users = enterprise-controlled identities

Step-by-step guide in real-world terms
For example:

“I want to manage my team under an enterprise trial: Step 1 – create an enterprise account. Step 2 – create or move your organization under it.”

Better error messages

If you try to create an org with your username → error should say “Your personal account cannot be transformed into an enterprise account. Instead, create an enterprise account and move your org under it.”

With a link to clear docs.

Visual diagram
A simple chart showing:
Enterprise → Organization(s) → Repositories → Teams/Users.