Clarify AWS Organization creation and Quickstart requirements #829
Conversation
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
This comprehensive update addresses user confusion and gaps in the documentation across three key areas: ## 1. Organization Creation Clarity (Terraform vs Console) - Clarified that AWS Organization is created with Terraform, not the console - Console steps are only for post-creation configuration (quotas, AWS RAM) - Added documentation for the manual creation + import option for teams that want to request quota increases early ## 2. Atmos & Configuration Clarity - Added Atmos primer explaining stacks, components, and catalogs - Provided concrete example of account.yaml structure with explanations - Added learning resources for Atmos beginners - Clarified the difference between docs and actual configurations needed ## 3. Commercial Model & Quickstart Requirements - Added prominent "How Commercial Open Source Works" explanation - Clarified that following docs without Quickstart/Jumpstart is not supported - Added early CTAs on Getting Started page to guide users to Choose Your Path - Added prerequisite checkpoints at critical entry points (accounts layer overview, prepare-aws-organization page, deploy-accounts page) ## Impact These changes prevent the exact user experience that prompted them: - User reads docs, answers design decisions, then gets stuck at "Check the configuration of the 'account' in the stack catalog" because configs don't exist without purchasing Quickstart/Jumpstart Users are now intercepted at multiple touchpoints with clear explanations of what's needed and friendly guidance to the right path. 🤖 Generated with Claude Code Co-Authored-By: Claude <[email protected]>
- Add missing Note component import in prepare-aws-organization.mdx - Add missing SecondaryCTA component import in intro.mdx Fixes CI build errors: - Error: Expected component `Note` to be defined - Error: Expected component `SecondaryCTA` to be defined 🤖 Generated with Claude Code Co-Authored-By: Claude <[email protected]>
The icon and title were wrapping to separate lines on the DocCard components. Changes: - Set .cardTitle to use flexbox (display: flex, align-items: center) - Added flex-wrap: nowrap to prevent wrapping - Set .icon to inline-flex for proper alignment This ensures the icon and title stay side-by-side as intended. 🤖 Generated with Claude Code Co-Authored-By: Claude <[email protected]>
Changed from 'Don't have the configs yet?' to more helpful and positive framing: 'Need help finding the configurations? Start here' This is friendlier and more action-oriented. Updated in: - docs/layers/accounts/accounts.mdx - docs/layers/accounts/prepare-aws-organization.mdx 🤖 Generated with Claude Code Co-Authored-By: Claude <[email protected]>
Changes: 1. Updated messaging throughout to 'Looking for the configurations? Start here' - More neutral and action-oriented than previous versions - Updated in accounts.mdx and prepare-aws-organization.mdx 2. Converted intro.mdx from info admonition + separate CTAs to ActionCard - More visually prominent and cohesive - CTAs now integrated into the card - Consistent with ActionCard pattern used elsewhere 🤖 Generated with Claude Code Co-Authored-By: Claude <[email protected]>
ActionCards were appearing too close to content below them. Added margin-bottom: 2em to .action-card for proper spacing. 🤖 Generated with Claude Code Co-Authored-By: Claude <[email protected]>
The 'How Commercial Open Source Works' admonition had sentences running together without proper spacing/paragraph breaks. Changes: - Split long paragraphs into shorter, more digestible chunks - Each major point now gets its own paragraph - Improves readability and prevents text from appearing as a wall This fixes the visual issue where sentences like 'the configuration.All our tools' and 'we sell.Why this matters:' were running together. 🤖 Generated with Claude Code Co-Authored-By: Claude <[email protected]>
Changed the Community section description to accurately reflect that it's a place for peer collaboration and knowledge sharing, not commercial support. Old: 'for those who want to engage with the SweetOps community and get support' New: 'for connecting with others who are building infrastructure with Cloud Posse's open source tools... a place to share experiences, learn from peers, and collaborate on common challenges' This better represents the community as a watering hole and talk shop for practitioners, not a support channel for the commercial reference architecture. 🤖 Generated with Claude Code Co-Authored-By: Claude <[email protected]>
Two changes in this commit: 1. Restore bullet points and numbering for markdown lists (Tailwind-compatible) - Added @layer base CSS with @apply directives for list-disc and list-decimal - Applies to .markdown and article contexts - Works with Tailwind's utility-first approach - Uses pl-6, my-4 spacing utilities 2. Refocus Community section on open source collaboration - Changed from generic 'connecting with others' to specific emphasis on 'collaborating on the development of Cloud Posse's open source' - Highlights PR reviews, problem-solving, and collective ecosystem building - Clarifies it's about working together to improve modules/components/tools 🤖 Generated with Claude Code Co-Authored-By: Claude <[email protected]>
Changed from 'Missing the Quickstart configurations?' to 'Looking for the configurations? Start here' to match the consistent messaging used throughout the docs. Also removed <strong> emphasis on 'Quickstart' for a cleaner appearance. 🤖 Generated with Claude Code Co-Authored-By: Claude <[email protected]>
Admonitions use display: inline on paragraphs to save vertical space, but paragraphs were running together without spacing between them. Added margin-right: 0.5em to .theme-admonition > div p to ensure proper spacing between inline paragraphs while maintaining the compact layout. Fixes the issue where text like 'the configuration.All our tools' appeared as one continuous string. 🤖 Generated with Claude Code Co-Authored-By: Claude <[email protected]>
The large Prerequisites admonition was taking up too much above-the-fold space when users first land on the page. Moved it from the top of the page to the end of the Prerequisites section (after 'Start your Geodesic shell before continuing') where it's more contextual and doesn't dominate the initial view. Users now see: 1. Intro text about Cold Start 2. First Time Using Atmos note 3. Quick overview table 4. Prerequisites section 5. THEN the detailed prerequisites admonition This provides better progressive disclosure and doesn't overwhelm new visitors. 🤖 Generated with Claude Code Co-Authored-By: Claude <[email protected]>
…ording Two changes: 1. Removed numbered list (1. 2. 3.) - keeping only checkmark emojis - Using both numbers and checkmarks was redundant - Each item now on its own line with just ✅ prefix - Cleaner visual presentation 2. Changed 'should be customized' to 'will be customized' - More assertive/definitive language - Reflects that customization is guaranteed, not conditional 🤖 Generated with Claude Code Co-Authored-By: Claude <[email protected]>
The page had two 'Prerequisites' headings which was confusing: - Section heading: ## Prerequisites - Admonition title: PREREQUISITES Changed the admonition title to 'Before You Begin' to differentiate it from the section heading and make it clear this is a different type of information (Quickstart requirements vs general prerequisites). 🤖 Generated with Claude Code Co-Authored-By: Claude <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Summary
This comprehensive update addresses user confusion and documentation gaps across three key areas:
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.
Atmos & Configuration Clarity: Added Atmos primer, concrete
account.yamlexamples, and learning resources for beginners. Clarified the difference between free docs and paid Quickstart configurations.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:
Changes
Testing
Users encountering these pages will now:
🤖 Generated with Claude Code
Co-Authored-By: Claude [email protected]