Simplify quickstart page for better user experience#2921
Closed
mintlify-development[bot] wants to merge 1 commit intomainfrom
Closed
Simplify quickstart page for better user experience#2921mintlify-development[bot] wants to merge 1 commit intomainfrom
mintlify-development[bot] wants to merge 1 commit intomainfrom
Conversation
- Streamlined intro from complex explanation to simple promise - Converted deployment to clear 4-step process - Prioritized web editor workflow over CLI for beginners - Simplified editing steps and removed decision fatigue - Updated next steps to focus on actionable customization tasks
![tembo[bot]](https://avatars.githubusercontent.com/in/1223475?s=60&v=4){kind=small}
| Mintlify uses a docs-as-code approach to manage your documentation. Every page on your site has a corresponding file stored in your documentation <Tooltip tip="Your documentation's source code where all files and their history are stored. The web editor connects to your documentation repository to access and modify content, or you can edit files locally in your preferred IDE.">repository</Tooltip>. | ||
| 1. Go to [mintlify.com/start](https://mintlify.com/start) | ||
| 2. Connect your GitHub account | ||
| 3. Create a new repository or select an existing one |
Contributor
There was a problem hiding this comment.
The numbered steps currently say "Connect your GitHub account", but the tip right below says you can skip GitHub. Might be less confusing if the steps call out that it’s optional.
Suggested change
| 3. Create a new repository or select an existing one | |
| 1. Go to [mintlify.com/start](https://mintlify.com/start) | |
| 2. Connect your GitHub account (optional) | |
| 3. Create a new repository or select an existing one (optional) | |
| 4. Complete the onboarding process |
| </Step> | ||
| <Step title="View your changes"> | ||
| Check your site to see the updated description live. | ||
| </Step> |
Contributor
There was a problem hiding this comment.
Small clarity tweak: publishing can take a moment; pointing folks to the dashboard avoids "why don’t I see it yet?" confusion.
Suggested change
| </Step> | |
| Refresh your site to see the updated description live. If you don’t see it yet, check the deployment status on the **Overview** page in your dashboard. |
| <AccordionGroup> | ||
| <Accordion title="Use the CLI instead"> | ||
| Prefer working locally? [Install the CLI](/installation) to edit files in your preferred editor and preview changes with `mint dev`. | ||
| </Accordion> |
Contributor
There was a problem hiding this comment.
For the CLI path, it might help to mention that pushing changes is what triggers a deploy (since the main flow now hides that detail).
Suggested change
| </Accordion> | |
| Prefer working locally? [Install the CLI](/installation) to edit files in your preferred editor, preview changes with `mint dev`, then commit and push to deploy. |
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.
Summary
Simplified the quickstart page to reduce complexity and improve the new user experience.
Changes made
Before/After comparison
Before: 146 lines with complex explanations, tooltips, and dual workflow tabs
After: 80 lines with direct, actionable steps
Rationale
The previous quickstart had too much complexity for new users:
The new version follows the project's content strategy of "just enough docs" and prioritizes getting users to success quickly.
Testing
mint devNote
Streamlines the
quickstart.mdxto reduce steps and focus on fastest path to a live site.Stepsand moves CLI to an accordion as an optional pathindex.mdx, publishing, and viewing changesWritten by Cursor Bugbot for commit 0d1594d. This will update automatically on new commits. Configure here.