docs icon indicating copy to clipboard operation
docs copied to clipboard

Clarify AWS Organization creation and Quickstart requirements

Open osterman opened this issue 4 months ago • 0 comments

Summary

This comprehensive update addresses user confusion and documentation gaps across three key areas:

  1. Organization Creation Clarity: Clarified that AWS Organization is created with Terraform (not console), and documented the manual creation + import option for teams wanting early quota requests.

  2. Atmos & Configuration Clarity: Added Atmos primer, concrete account.yaml examples, and learning resources for beginners. Clarified the difference between free docs and paid Quickstart configurations.

  3. Commercial Model & Quickstart Requirements: Added prominent explanations that following docs without Quickstart/Jumpstart is not supported, with early CTAs and prerequisite checkpoints at critical entry points.

Motivation

A user experienced this exact frustration: Read docs → Answer design decisions → Get stuck at "Check the configuration of the 'account' in the stack catalog" because those files don't exist without Quickstart.

These changes intercept users at multiple touchpoints with clear guidance:

  • Entry point (Getting Started): Early CTA to "Choose Your Path"
  • Accounts layer (overview page): "Before You Start" caution
  • Prepare phase (critical chokepoint): Explicit prerequisites checklist
  • Deployment phase (last chance): Required configurations notice

Changes

  • docs/intro/intro.mdx: Added above-fold CTA buttons + "Get Started the Right Way" info box
  • docs/intro/path.mdx: Enhanced commercial model explanation, improved Quickstart copy
  • docs/layers/accounts/accounts.mdx: Added "Before You Start" caution
  • docs/layers/accounts/prepare-aws-organization.mdx: Added prerequisites checklist with explicit warning about the "stuck" scenario
  • docs/layers/accounts/deploy-accounts.mdx: Added Atmos primer, account.yaml example, config requirements notice, and organization creation methods clarification
  • docs/layers/accounts/tutorials/manual-configuration.mdx: Clarified Terraform vs console, added manual creation + import documentation

Testing

Users encountering these pages will now:

  1. See clear messaging about Quickstart/Jumpstart requirements
  2. Understand what Atmos is and how to use basic commands
  3. Have concrete config examples to review
  4. Have multiple exit ramps to "Choose Your Path" if they don't have configs

🤖 Generated with Claude Code

Co-Authored-By: Claude [email protected]

osterman avatar Oct 29 '25 15:10 osterman