Rework Next.js quick start guide (wizard)

[inventarSarah]

DESCRIBE YOUR PR

Reworked the Next.js Getting Started Guide into a Quick Start Guide.
See #12288 (and parent #11859)

IS YOUR CHANGE URGENT?

Help us prioritize incoming PRs by letting us know when the change needs to go live.

• Urgent deadline (GA date, etc.):
• Other deadline:
• None: Not urgent, can wait up to 1 week+

SLA

• Teamwork makes the dream work, so please add a reviewer to your PRs.
• Please give the docs team up to 1 week to review your PR unless you've added an urgent due date to it.
  Thanks in advance for your help!

PRE-MERGE CHECKLIST

Make sure you've checked the following before merging your changes:

• Checked Vercel preview for correctness, including links
• PR was reviewed and approved by any necessary SMEs (subject matter experts)
• PR was reviewed and approved by a member of the Sentry docs team

LEGAL BOILERPLATE

Look, I get it. The entity doing business as "Sentry" was incorporated in the State of Delaware in 2015 as Functional Software, Inc. and is gonna need some rights from me in order to utilize my contributions in this here PR. So here's the deal: I retain all rights, title and interest in and to my contributions, and by keeping this boilerplate intact I confirm that Sentry can use, modify, copy, and redistribute my contributions, under Sentry's choice of terms.

EXTRA RESOURCES

• Sentry Docs contributor guide

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
sentry-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jan 30, 2025 11:24am

2 Skipped Deployments

Name	Status	Preview	Comments	Updated (UTC)
changelog	⬜️ Ignored (Inspect)	Visit Preview		Jan 30, 2025 11:24am
develop-docs	⬜️ Ignored (Inspect)	Visit Preview		Jan 30, 2025 11:24am

[codecov]

Bundle Report

Changes will increase total bundle size by 228 bytes (0.0%) ⬆️. This is within the configured threshold ✅

Detailed changes

Bundle name	Size	Change
sentry-docs-server-cjs	10.37MB	234 bytes (0.0%) ⬆️
sentry-docs-client-array-push	9.3MB	6 bytes (-0.0%) ⬇️

[lforst]

I love that we give this page some attention! Since this page is so critical though, we should be rather selective how much we bombard users with information. Additionally, the information we give them needs to be bulletproof. Anything in the wrong place will spark immense confusion.

[lforst]

I would honestly remove this entire section. It's irrelevant to the setup in the docs since it's pretty much always gonna be the same because the wizard will already let you choose.

[inventarSarah]

Please see my response to a similar comment here: #12291 (comment)

[lforst]

There are very conflicting opinions on adding a paragraph like this. IIRC we flipped back and fourth 4 times on having this paragraph vs not having it in the last 2 years.

I personally, don't think SDK onboarding is the place to go into that stuff. I do however see the value behind capturing people who know nothing about Sentry yet. How about instead of having a 3 point paragraph, we do a simple sentence like, "This guide will tell you how to hook up your application with the Sentry SDK. If you want to know more about Sentry itself go here."

[inventarSarah]

Yes, it's a hot topic, as I've learned :)! There are already discussions about moving these features to another location (e.g. an SDK landing page). And then, as you wrote, for example, link to it from the quick start page.
However, since we currently don't yet have a place for it, I'd like to leave the information here.
Or do you know of a page we could link to?
If not, is it okay for you to leave it like this for the time being?

I'm also working on the Next.js quick start guide for manual setup -> this page will also need to communicate the features to the user (including onboarding option checkboxes). How we will solve this in detail will probably also influence the quick start guide for the wizard setup (and vice versa).

[lforst]

Makes sense, we can keep it for now!

[lforst]

I don't like this section because the wizard will tell you to do this. We should avoid putting information in multiple places. If the wizard is missing information that we would have added here, we should add it to the wizard instead. My working theory is that once people run the wizard command, they will not look back into the docs until they are done with looking at the error in Sentry. At which point all of this text is already irrelevant. What's more important in that moment is the Next Steps.

[inventarSarah]

I understand you're suggesting we simplify the guide to only include "Prerequisites," "Install," and "Next Steps." -- Did I get this right?

This is a new idea, and I'd like to share it with the others to get their input as well (hopefully tomorrow).

I see the advantages of having a shorter guide and relying more on the wizard.
However, there are a few points we need to be mindful about:

• once the terminal window in which the wizard ran is closed, all its information is gone; the quick start guide is always accessible
• "they will not look back into the docs until they are done with looking at the error in Sentry" - on the other hand, we probably also have users who don't read all the text in the terminal (I'm such a candidate, for example). Especially everything that comes after the green Success message may be perceived as "not important"; ideally, we can make both of these user types happy
• many users who use this type of guide are probably new and don't know much about Sentry yet. So the quick start guide is a great place to introduce them to features beyond error monitoring and provide links to more information -> but we have also talked about providing this info somewhere else (eg. on a landing page Have quick start as a menu item #12289)

this is also relevant to your comment on the features: /#discussion_r1910162943

[lforst]

These points make sense. We can keep it, but I would advocate for half a sentence like "If you haven't done so through the setup wizard, go through the following steps to....". That way people will know not to do the same thing twice.

[inventarSarah]

Thank you -- I'll rewrite this section for sure because I now see that it can be misleading!

[lforst]

another problem: it may not always be localhost:3000 depending on the app

[inventarSarah]

I've updated this to be more like what we currently have in the wizard

[chargome]

Nice rework!

Let's make sure to merge in #12293 before this one and also see if @lforst has any comments here

[inventarSarah]

@lfrost @chargome
For testing purposes, I have updated this quick start guide with some ideas from the team.

This also addresses some of your feedback, so I hope you can find some improvements in these changes too!

What's changed:

• Step 1 should be Install (the old Step 1 wasn't actionable, which does not make sense for something called "Step" :D)
• Test: moved the features list into an Expandable in the Install section
• Test: moved the list in View Captured Data in Sentry into an Expandable
• Test: moved the Expandable about Turbopack into the Verify section

I like that the guide is more actionable now and that we can still include information without scaring the user with an overly long page (by using the Expandables). However, I feel like there are too many boxes now and that it might not be pleasant to look at.
I need to revisit the page with refreshed eyes later again :)
In the meantime, please have a look if you want, and I will also ask Salma to do the same

Thank you!!

[whitep4nth3r]

Great work. I love how the full guide fits completely on my weird vertical type monitor as a bonus. ✅

[coolguyzone]

I know Issues is our error monitoring product, but clicking on 'Error Monitoring' and being directed to the 'Issues' page might be confusing for those less familiar with Sentry.

What do you think about having this anchor text say 'issues' and providing some context in the description?

e.g. "Issues (always enabled): Sentry's core error monitoring product that automatically reports errors . . ."

[inventarSarah]

Let's do as you suggested! This is also a good idea because we also write about this "Issues" page under "Need help locating the captured errors in your Sentry project?"

Updated it 👍

[coolguyzone]

What do you think about linking to https://sentry-docs-git-smi-quick-startnextjs.sentry.dev/product/explore/session-replay/web/ instead of the /getting-started/ page here? I feel like it provides more context and feels more inline with the content on two links above.

[inventarSarah]

Yes, good idea!
Updated 👍

[coolguyzone]

Suggested change

	- Add a Next.js instrumentation hook to your project (`instrumentation.ts`)
	- Addition of Next.js instrumentation hook to your project (`instrumentation.ts`)

[coolguyzone]

Hey @inventarSarah, this looks great! I added some comments/suggestions, feel free to push back/reject any of them. 🏄‍♂️

[codyde]

This looks great! I looked over the other feedback and saw you incorporated it all. This is all good on my side.

LGTM!