(DOCSP-39525): Consolidate Create and Delete Users page #3289

dacharyc · 2024-06-07T20:51:56Z

Pull Request Info - SDK Docs Consolidation

Jira ticket: https://jira.mongodb.org/browse/DOCSP-39525

Staged Page

Create, Delete, and Remove Users

Page Source

Add links to every SDK's pages where you got the SDK-specific information:

PR Author Checklist

Before requesting a review for your PR, please check these items:

Open the PR against the feature-consolidated-sdk-docs branch instead of master
Tag the consolidated page for:
- genre
- meta.keywords
- meta.description

Naming

Update Realm naming and the language around persistence layer/local/device per this document
Include .rst files comply with the naming guidelines

Links and Refs

Create new consolidated SDK ref targets starting with "_sdks-" for relevant sections
Remove or update any SDK-specific refs to use the new consolidated SDK ref targets
Update any Kotlin API links to use the new Kotlin SDK roles

Content

Shared code boxes have snippets or placeholders for all 9 languages
API description sections have API details or a generic placeholder for all 9 languages
Check related pages for relevant content to include
Create a ticket for missing examples in each relevant SDK: Consolidation Gaps epic

Reviewer Checklist

As a reviewer, please check these items:

Shared code example boxes contain language-specific snippets or placeholders for every language
API reference details contain working API reference links or generic content
Realm naming/language has been updated
All relevant content from individual SDK pages is present on the consolidated page

github-actions · 2024-06-07T20:53:04Z

Readability for Commit Hash: 1a7b185

You can see any previous Readability scores (if they exist) by looking
at the comment's history.

Readability scores for changed documents:

source/sdk/users: Grade Level: 29.9, Reading Ease: -67.95
source/sdk/users/authenticate-users: Grade Level: 10.2, Reading Ease: 31.85
source/sdk/users/manage-email-password-users: Grade Level: 7.8, Reading Ease: 48.97
source/sdk/users/create-and-delete-users: Grade Level: 10.7, Reading Ease: 46.67

For Grade Level, aim for 8 or below.

For Reading Ease scores, aim for 60 or above:

Score	Difficulty
90-100	Very Easy
80-89	Easy
70-79	Fairly Easy
60-69	Medium
50-59	Fairly Hard
30-49	Hard
0-29	Very Hard

For help improving readability, try Hemingway App.

krollins-mdb

Nice job, @dacharyc! I have mostly minor comments. It wasn't immediately clear to me what content was added verbatim and what needed to be messaged. Feel free to ignore comments on content that was migrated as-is.

krollins-mdb · 2024-06-12T17:31:39Z

source/sdk/users/create-and-delete-users.txt

+.. tip:: Atlas Device SDK Users Differ from Other Types of Atlas Users
+
+   Atlas Device SDK users are distinct from :ref:`database users <mongodb-users>`
+   or :ref:`Atlas account users <atlas_users>`. SDK users are bounded by the
+   App Services App where they are registered, and only have access to
+   resources you provide through the App. Your application can let SDK users:
+
+   - :ref:`Read and write from a synced database <sdks-write-synced-database>`
+   - :ref:`Call an Atlas Function <sdks-call-function>`
+   - Call :ref:`Data API <data-api>` or :ref:`custom HTTPS endpoints <custom-endpoints>`
+   - Read and write from specified collections and databases in MongoDB Atlas
+     through :ref:`the MongoClient API <sdks-access-mongodb>`
+
+   SDK users do not have direct Atlas database access, or direct Atlas account
+   access. It is your responsibility to manage these application users,
+   including complying with data retention or deletion policies and regulatory
+   requirements where you publish your applications.


We should consider making this its own section. I can see support folks wanting to link to this content - that's harder when it's in an admonition.

I think it's also important enough to be its own section with its own heading.

Good call. This is net new content that I realized was totally missing as I was creating this page. It got bigger as I was fleshing it out. I think you're right, it probably warrants being its own section. Updating!

krollins-mdb · 2024-06-12T17:40:03Z

source/sdk/users/create-and-delete-users.txt

+You can also associate :ref:`metadata <sdks-user-metadata>` or 
+:ref:`custom data <sdks-custom-user-data>` with user accounts.
+
+Users can have multiple identities. For more information, refer to
+:ref:`sdks-link-user-identities`.
+
+Your app can manage multiple users on a device. For more information, refer
+to :ref:`sdks-multi-user-applications`.
+
+For more information about authentication providers, identities, and user
+sessions, refer to :ref:`Authenticate & Manage Users <users-and-authentication>`
+in the App Services documentation.


This block of content feels like a grab bag of related things and not particularly relevant? I was confused by the shift from the first paragraph to this block because there's not contextual shift from "here's what this thing is" to "here's related stuff".

We could remove the content block, embed it in a place with more context (like the Create Users section), or establish more context here.

In the case of the latter, maybe something like this?

Suggested change

You can also associate :ref:`metadata <sdks-user-metadata>` or

:ref:`custom data <sdks-custom-user-data>` with user accounts.

Users can have multiple identities. For more information, refer to

:ref:`sdks-link-user-identities`.

Your app can manage multiple users on a device. For more information, refer

to :ref:`sdks-multi-user-applications`.

For more information about authentication providers, identities, and user

sessions, refer to :ref:`Authenticate & Manage Users <users-and-authentication>`

in the App Services documentation.

When you create a new user, keep in mind these features:

- You can associate :ref:`metadata <sdks-user-metadata>` or

:ref:`custom data <sdks-custom-user-data>` with user accounts.

- Users can have multiple identities. For more information, refer to

:ref:`sdks-link-user-identities`.

- Your app can manage multiple users on a device. For more information, refer

to :ref:`sdks-multi-user-applications`.

- For more information about authentication providers, identities, and user

sessions, refer to :ref:`Authenticate & Manage Users <users-and-authentication>`

in the App Services documentation.

I don't necessarily love that framing, but hopefully the idea makes sense?

Yeah, it is a grab bag of features. I understand the point you're making here - I'll iterate on this a little.

krollins-mdb · 2024-06-12T20:22:25Z

source/sdk/users/create-and-delete-users.txt

+If your app uses email/password authentication, you must manually register a
+user to create a user object. For more information about registering
+email/password users, refer to :ref:`sdks-email-password-user-register`.


I was a bit confused by what "manually" refers to here. I'm afraid not all of the SDKs work the same way here. The JS SDK's registerUser() method doesn't return anything - it doesn't create a user object. The .NET SDK also doesn't create a user object by registering.

I guess I'm assuming this refers to an on-device user object and not one in App Services. These methods do create App Services users.

Yeah, I was referring to App Services users. I realize with this feedback that this is unclear. I'll wordsmith this a bit.

krollins-mdb · 2024-06-12T20:26:16Z

source/sdk/users/create-and-delete-users.txt

+Calling the user delete method performs the following:
+
+- Deletes synced databases associated with the user from the device.
+- deletes the ``User`` object from the Atlas App Services server


Suggested change

- deletes the ``User`` object from the Atlas App Services server

- Deletes the ``User`` object from the Atlas App Services server

krollins-mdb · 2024-06-12T20:31:33Z

source/includes/sdk-examples/users/create-delete-users-delete-users-from-atlas.rst

+         .. literalinclude:: /examples/MissingPlaceholders/example.m
+            :language: objectivec
+
+     - id: swift


Is it intentional that the Swift examples have XCTAssert statements? Seems problematic for copy/paste. Probably not worth addressing as part of the consolidation work.

It is intentional as we were experimenting with different ways to show information in code examples. But it's a direction we decided not to take after this, and probably warrants being updated/removed. I can make it non copyable for now, and will update the Swift follow up ticket for this page to remove the asserts.

krollins-mdb · 2024-06-12T20:32:27Z

source/includes/sdk-examples/users/create-delete-users-delete-users-from-atlas.rst

+     - id: typescript
+       content: |
+
+         .. literalinclude::  /examples/MissingPlaceholders/example.ts


We should use the JavaScript example here. I know it's a .js file, but this is a case where TypeScript would look and behave exactly the same way.

I'm happy to make this change here. But generally there are a lot of places in the docs where we are missing either a JS or TS example, and I'm using the "missing example" placeholder because I don't know where those would be the same example. We'll need to make updates as part of the follow up work.

I've kept the "missing example" includes files generic, but I could create includes for places where we have JS or TS that say "This example is missing in Typescript - see the Javascript example" or "see the Typescript example" if you think that would be a better experience? It would create more maintenance overhead for us to use the right include and remember to update it when that changes, but we could definitely do that.

docs-builder-bot · 2024-06-18T19:13:05Z

✨ Staging URL: https://preview-mongodbmongodb.gatsbyjs.io/realm/feature-consolidated-sdk-docs/

🪵 Logs

job log: c33fc2223168a938e8bbd52c7c91630e68bfa0e0

Draft a Create and Delete Users page

8fc5d18

dacharyc added the merge to feature branch Unreleased feature - do not merge to Master label Jun 7, 2024

dacharyc marked this pull request as ready for review June 7, 2024 20:55

krollins-mdb approved these changes Jun 12, 2024

View reviewed changes

Apply review feedback

1a7b185

dacharyc merged commit c33fc22 into mongodb:feature-consolidated-sdk-docs Jun 18, 2024
5 checks passed

dacharyc deleted the DOCSP-39525 branch June 18, 2024 19:10

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

(DOCSP-39525): Consolidate Create and Delete Users page #3289

(DOCSP-39525): Consolidate Create and Delete Users page #3289

dacharyc commented Jun 7, 2024 •

edited by krollins-mdb

Loading

github-actions bot commented Jun 7, 2024 •

edited

Loading

krollins-mdb left a comment

krollins-mdb Jun 12, 2024

dacharyc Jun 18, 2024

krollins-mdb Jun 12, 2024

dacharyc Jun 18, 2024

krollins-mdb Jun 12, 2024

dacharyc Jun 18, 2024

krollins-mdb Jun 12, 2024

krollins-mdb Jun 12, 2024

dacharyc Jun 18, 2024

krollins-mdb Jun 12, 2024

dacharyc Jun 18, 2024

docs-builder-bot commented Jun 18, 2024

	- deletes the ``User`` object from the Atlas App Services server
	- Deletes the ``User`` object from the Atlas App Services server

(DOCSP-39525): Consolidate Create and Delete Users page #3289

(DOCSP-39525): Consolidate Create and Delete Users page #3289

Conversation

dacharyc commented Jun 7, 2024 • edited by krollins-mdb Loading

Pull Request Info - SDK Docs Consolidation

PR Author Checklist

Naming

Links and Refs

Content

Reviewer Checklist

github-actions bot commented Jun 7, 2024 • edited Loading

krollins-mdb left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

docs-builder-bot commented Jun 18, 2024

🪵 Logs

dacharyc commented Jun 7, 2024 •

edited by krollins-mdb

Loading

github-actions bot commented Jun 7, 2024 •

edited

Loading