DOCSP-12448: Backend Phase 2 Tutorial

[nathan-contino-mongo]

Pull Request Info

Issue JIRA link:

https://jira.mongodb.org/browse/DOCSP-12448

Docs staging link (requires sign-in on MongoDB Corp SSO):

https://docs-mongodbcom-staging.corp.mongodb.com/realm/nathan.contino/DOCSP-12448/tutorial/realm-app.html

[cbush]

This is truly excellent and I completely agree with the need to provide clear step-by-step instruction on the Atlas setup part. However, I'm also worried that the page is too daunting as-is and the pertinent information for a keen reader is buried under Atlas information that should be handled for us in the Atlas UI. Can we move much of the Atlas guidance to a "Step-by-step Atlas setup guide" page (in our docs) and keep this page focused on the Realm CLI setup and import?

Also, I think a few steps could be combined, not just for the sake of seeming like there are fewer steps but also because they're usually done together anyway (such as cloning and importing the backend or creating an API key and authenticating the CLI).

Assuming you agree with my perspective, I'm hoping you can basically keep the content as-is but move the detail to another page and link to it for the truly lost. If you don't agree with moving the Atlas step, I would at least like the "Overview" section to have the more pertinent information brought to the top and explain why we're doing all this stuff up front ("we've created a backend for you, which you need to import...")

Thanks!

[cbush]

I understand the motivation for writing the section like this, but I'm finding this list and page more daunting than it needs to be. Let's try rewriting this so that the emphasis is on the Realm parts with the key points that aren't covered by the Atlas sign-up flow called out. We could even move the detailed Atlas stuff (excellent quality) to another page so as not to frighten people away.

The key points are:

• We have prepared the backend Realm app for you, complete with the functions, triggers, schemas, and sync configuration you'll need to connect with one of our front-end apps.
• You can import the backend app using the Realm CLI with an Atlas API key.
• You need an Atlas cluster running MongoDB 4.4 to store the data for your task tracker app. You can get started with a free Atlas cluster.

Then the important steps of Atlas:

• Make sure you build your cluster with MongoDB 4.4
• Make sure your cluster is in the right region

Then link out to this text in another document if needed. ("Follow our step-by-step guide to creating a free Atlas account, 4.4 cluster, etc. etc...")

[nathan-contino-mongo]

Reworked with some of this, but leaving more explicit steps for now -- we'll see if drew/ian/katherine have similar feedback, or if they like the fact that this tutorial doesn't expect any prior knowledge of any of our products.

[KAMaughan]

👋 Hello! I have a few thoughts here:

1. An important nit-pick: the overview lists the various steps numerically (1,2,3,4,5) but as you read through the steps each section is labeled alphabetically (A,B,C,D,E). Let's make this consistent.

2. This does feel very long for only Section 1: Set-Up, out of a multi-section tutorial. I think there are a few ways we can mitigate any daunting feelings.

First: What do we want to do with hand-holding? I write this assuming we're aiming to orient a user and appropriately set expectations, particularly for users who are totally new to Atlas.

Guided by that, I think of these instructions can be simplified, and others can better help to set expectations and essentially reduce friction/concern - particularly where new users might be wondering, "How long does this take?" or "What does this mean?"

Concrete suggestions:

Add time estimates for each step, e.g:
"To use our pre-made backend, you’ll have to:

1. Create an Atlas account, if you don’t already have one. (3 min)
2. Create a free Atlas cluster running MongoDB 4.4. (5 min)
3. Install the Realm CLI. (3 min)
4. Add a programmatic API key to your Atlas project and use it to log into the Realm CLI. ([x] min)
5. Use the Realm CLI to create a new Task Tracker backend Realm app with our pre-made Task Tracker backend. ([x] min)"_

I'd also recommend adding that as a first sentence to each section, e.g.
"Time Estimate: [x minutes] Now that you’ve created a cluster to use as the data source for your Realm app, we need some way to create the app itself."

Another suggestion: remove certain steps where we can safely assume the user understands, due to it being a very typical/normal pattern of behavior, e.g. - if it will take significantly longer to read the instructions than it will to complete the task, we probably over-indexed on explaining.

Example of where we could cut some steps to reduce length:

_A. Create an Atlas Account
To begin, you’ll need a MongoDB Atlas account. If you’ve already got an existing MongoDB Atlas Account, you can proceed to the next step. If you don’t have an Atlas account, follow the steps below to create one:

Navigate to the MongoDB Atlas login page.

1. Click Login.
   2. Either enter a new set of user credentials or click the Sign Up with Google button.
   3. Click the checkbox to accept the Privacy Policy and Atlas Terms & Conditions.
2. Click Sign Up to create your account.
3. Follow the prompts to create an organization and project in your Atlas account. You can use the default suggested names or enter your own._

Things I like:

• Where we've added screen shots
• That we're not assuming familiarity with Atlas

[nathan-contino-mongo]

@KAMaughan thanks so much for the feedback! If you check out the latest version of the staging environment (just refresh or follow the link again) you should see some updates based on your feedback. I think time estimates are super helpful and consistency with the major step labeling (letters) is a huge improvement as well. Trimmed a few unnecessary steps as well, though I didn't want to go overboard on that just yet. Let me know what you think!