(DOCSP-39513): Consolidate Create page #3270

dacharyc · 2024-05-22T14:52:28Z

Pull Request Info - SDK Docs Consolidation

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

Staged Page

New consolidated pages:

Existing pages, ported over to the consolidated IA and updated for product naming/metadata:

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
Note for Reviewer: The .rst files were named for a single create page. Having split the create page into 3, the names no longer comply with the guidelines. As this is around ~140 files, I didn't want to rename them all - but we may want to consider whether I should go through the effort, and/or what the naming guidelines look like as the IA evolves.

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-05-22T14:53:45Z

Readability for Commit Hash: 19b0f29

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

Readability scores for changed documents:

source/sdk/react-to-changes: Grade Level: 8.7, Reading Ease: 41.22
source/sdk/model-data/relationships: Grade Level: 19.0, Reading Ease: -12.45
source/sdk/model-data/supported-types: Grade Level: 9.4, Reading Ease: 39.4
source/sdk/model-data/object-models: Grade Level: 8.1, Reading Ease: 48.06
source/sdk/files/configure-and-open: Grade Level: 6.8, Reading Ease: 67.76
source/sdk/crud/threading: Grade Level: 9.2, Reading Ease: 40.01
source/sdk/crud/update: Grade Level: 11.9, Reading Ease: 22.07
source/sdk/crud/read: Grade Level: 8.1, Reading Ease: 58.89
source/sdk/crud/create: Grade Level: 8.8, Reading Ease: 57.06
source/sdk/crud/create/create-object-types: Grade Level: 9.4, Reading Ease: 50.23
source/sdk/crud/create/create-property-types: Grade Level: 8.8, Reading Ease: 51.65

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.

… directory

cbullinger

Still need to review Create Property Types, but figured there's plenty of feedback for you to sift through ^{so sorry}

cbullinger · 2024-06-20T17:31:22Z

source/sdk/crud.txt

@@ -15,7 +15,7 @@ Read and Write Data
 The following pages contain information about how to read and write data, 
 manage objects across threads, and use the Atlas Device SDK query engines:

- :ref:`sdks-crud-create`
+- :ref:`sdks-create-object-methods`


should this be updated now that the consolidated page is split into 3 child pages under Create?

FYI I've changed this back to sdks-crud-create after moving this back to a container page with content - i.e. a landing page. So this can be the main destination for "create" content.

source/sdk/crud/create/create-object-types.txt

cbullinger · 2024-06-21T14:26:17Z

source/sdk/crud/create/create-methods.txt

+.. _sdks-create-object-methods:
+
+=====================
+Create Object Methods


[nit] This feels out of place with the two other child page titles. plus the "methods" renders the title a noun instead of an action, no?

Capturing this detail on the PR in case there are questions in the future. Cory and I discussed this offline and decided to try it with this page as a parent page called "Create Objects" and the other two pages as child pages, instead of the three being sibling pages. We can change this in the future if we decide this is a pattern we don't want to use (the create methods as the landing page) - we can revisit before we merge the feature branch and move the content if we need to.

source/sdk/crud/create/create-methods.txt

cbullinger · 2024-06-21T14:28:56Z

source/sdk/crud/create/create-methods.txt

+:ref:`sdks-configure-and-open-database` or 
+:ref:`sdks-configure-and-open-synced-database`.


[note] it's really hard to parse these two links in the rendered text since these page titles are very nearly identical

cbullinger · 2024-06-24T13:21:56Z

source/includes/api-details/dart/crud/create-realm-object-description.rst

@@ -11,6 +11,7 @@ You can also return values from the write transaction callback function.

 .. warning:: Write RealmObjects to One Realm File


is this unique to the Flutter SDK? if so, should we make that clear? it seems potentially confusing to see this big red warning that seems potentially applicable to other sdks

The exception type is probably specific to Flutter. But the general info applies to more than one SDK - I know, for example, in Swift the DB throws an error if you try to write an object to a DB that is already managed by another DB.

We do explain that in the "Managed Objects" section, with a link to the section on copying a managed object to another DB. So maybe this warning isn't needed? I'll have a think about it.

cbullinger · 2024-06-24T13:27:12Z

source/sdk/crud/create/create-object-types.txt

+For more information about modeling an object, refer to: 
+:ref:`sdks-object-models`.
+
+.. include:: /includes/sdk-examples/crud/create-realm-object-model.rst


fyi - we should models for all of the Kotlin examples, so these should be easy to pop in as part of the follow-up tickets

source/sdk/crud/create/create-object-types.txt

cbullinger

Amazing job, @dacharyc. This was a tremendous amount of work. I'm sorry it took me so long to finish my review!

source/sdk/crud/create/create-property-types.txt

cbullinger · 2024-06-24T20:10:39Z

source/sdk/crud/create/create-property-types.txt

+~~~~~~~~~~~~~~~~~~~~~
+
+Like their native counterparts, the SDK's set data type stores unique values.
+These values may be of any supported type except another collection.


in Kotlin, they can't contain an embedded object either

source/sdk/crud/create/create-property-types.txt

source/includes/api-details/java/crud/create-counter-property-type-java-description.rst

cbullinger · 2024-06-24T22:52:30Z

source/includes/api-details/javascript/crud/create-counter-property-type-not-supported.rst

@@ -0,0 +1 @@
+JavaScript does not currently have a dedicated counter property type.


it does now! 🥳 the new page should be available to merge to the feature branch this week

Co-authored-by: cbullinger <115956901+cbullinger@users.noreply.github.com>

docs-builder-bot · 2024-06-25T21:02:33Z

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

🪵 Logs

job log: ae0e146320dfba81a316ed542a0ad669e5a3a825

Update tab IDs in PoC stub content

b6de91a

dacharyc added 28 commits May 22, 2024 11:24

Test adding IO code block for Kotlin

1e5a5b2

Update naming and Kotlin links

5439868

Add Create or Update content

9a10b93

Add mixed property type

54d233d

Add details about creating a List property, flesh out page ToC

439d26b

Add creating geospatial data

b55c6d3

Fix snooty build error

771dd89

Add create multiple objects details

a51f41e

Add details about initializing objects with a value

71d8730

Add details for creating objects from JSON

4d3a074

Add details about copying a managed object to another instance

4c59437

Add details about creating a counter property type

cdc6d0b

Add details about creating a timestamp property

1d356b2

Add create Object ID details

0560132

Add details about creating a UUID property type

e1c959c

Add create set property details

e83a7fa

Add create dictionary property details

00345a2

Add create relationship property details

437558d

Fix snooty build error

3091195

Add details about creating objects in the background

3b47dff

Add Swift Concurrency and Use Realm with Actors to new Apple platform…

bc519af

… directory

Update Swift concurrency pages for product naming and updated refs

c8bd56b

Fix snooty build errors

d1a72ee

Split Create content across multiple pages

0aa049e

Update ToC and refs

3b6a6dc

Remove OTP

61a47a9

Rename rst to txt

6df1040

Fix snooty build errors

9d2b19c

dacharyc marked this pull request as ready for review May 24, 2024 21:01

Update naming

f39ab91

dacharyc added the merge to feature branch Unreleased feature - do not merge to Master label May 24, 2024

cbullinger self-requested a review June 20, 2024 15:24

cbullinger reviewed Jun 24, 2024

View reviewed changes

cbullinger approved these changes Jun 24, 2024

View reviewed changes

dacharyc and others added 8 commits June 25, 2024 09:33

Merge branch 'feature-consolidated-sdk-docs' into DOCSP-39513

3193d0e

Apply suggestions from review

c8657b2

Co-authored-by: cbullinger <115956901+cbullinger@users.noreply.github.com>

Fix snooty build errors and make missing placeholders non-copyable

ba686c7

Try include with proper section headers

4a4640f

Try Create as landing page with content

d91db04

Fix snooty build error

6239d0c

Apply review feedback

fb89087

Apply review feedback

19b0f29

dacharyc merged commit ae0e146 into mongodb:feature-consolidated-sdk-docs Jun 25, 2024
6 checks passed

dacharyc deleted the DOCSP-39513 branch June 25, 2024 21:00

		:ref:`sdks-configure-and-open-database` or
		:ref:`sdks-configure-and-open-synced-database`.

		@@ -11,6 +11,7 @@ You can also return values from the write transaction callback function.

		.. warning:: Write RealmObjects to One Realm File

		@@ -0,0 +1 @@
		JavaScript does not currently have a dedicated counter property type.

(DOCSP-39513): Consolidate Create page #3270

(DOCSP-39513): Consolidate Create page #3270

Uh oh!

Conversation

dacharyc commented May 22, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Info - SDK Docs Consolidation

PR Author Checklist

Naming

Links and Refs

Content

Reviewer Checklist

Uh oh!

github-actions bot commented May 22, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cbullinger left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cbullinger left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

docs-builder-bot commented Jun 25, 2024

🪵 Logs

Uh oh!

Uh oh!

dacharyc commented May 22, 2024 •

edited

Loading

github-actions bot commented May 22, 2024 •

edited

Loading