DOCSP-35947: write operations modify documents

[ccho-mongodb]

JIRA: https://jira.mongodb.org/browse/DOCSP-35947

Note for the reviewer:

This contains some updates to the insert documents section (added new fields to the sample doc).
This is one of three tickets to document the update operations. The other two are:

• Upsert
• Update arrays

Staging:
https://preview-mongodbcchomongodb.gatsbyjs.io/laravel/DOCSP-35947-write-operations-modify-documents/fundamentals/write-operations/#modify-documents

Checklist

• Add tests and ensure they pass
• Add an entry to the CHANGELOG.md file
• Update documentation for new features

[norareidy]

Looks good, requesting changes since I left a couple questions!

[norareidy]

I: I think this sentence is incomplete. You could add something like this:

Suggested change

	When the ``save()`` method succeeds, the model instance on which you called the
	method.
	When the ``save()`` method succeeds, the model instance on which you called the
	method contains the updated values.

[ccho-mongodb]

Whoops, good catch! Will update.

[norareidy]

S: not necessary, but I like the detailed description of the code example in lines 86-94. Could be helpful to introduce this code example with more specific info

[ccho-mongodb]

Is there specific info that you think might be helpful to add? I think the insert example adds type information which sets up the rest of the examples on the page, but could be repetitive and draw away from the focus of the rest of the examples.

[norareidy]

I was thinking of specifying which fields / values you're updating (venue, ticketsSold), but agreed that this could be repetitive and I think it's fine as is!

[norareidy]

Q: this description is a little confusing - what is returning the "object collections"? Are you using "documents" and "object collections" interchangeably in this sentence?

[ccho-mongodb]

I'll replace the sentence with what I think might be less confusing.

I think I meant collection object. I can clarify further by using either the class name or adjective "Eloquent".

[norareidy]

S: I think you can condense this description a little; also, the other mentions of "fluent syntax" use "the", so I'd do the same here

Suggested change

	The following example shows how to update a document by using fluent syntax to
	retrieve the first match and apply updates to the matching document:
	The following example shows how to use the fluent syntax to
	retrieve and update the first matching document:

[ccho-mongodb]

Good suggestion, thanks!

[norareidy]

S: since collection usually refers to a MongoDB collection, using that word here (as a synonym of "group", from my understanding) could be misleading. You could change to:

Suggested change

	retrieve a collection of model objects that match your criteria and then
	retrieve multiple model objects that match your criteria and then

[ccho-mongodb]

Will clarify the connection between MongoDB documents and a Laravel collection object.

[norareidy]

S: same comment regarding "collection" as above (unless you are referring to a whole MongoDB collection?)

[ccho-mongodb]

Thanks for pointing this out. I'll make sure to establish the connection between "documents" and "Laravel collection objects" when necessary, and otherwise use only one of those terms in a paragraph.

[norareidy]

S: [nit] to avoid repeating "documents":

Suggested change

	existing documents or to insert a document if no documents match the search
	existing documents or to insert a document if none match the search

[norareidy]

LGTM!

[norareidy]

S: Since this example demonstrates how to update documents by chaining methods together:

Suggested change

	The following example shows how to update a document to retrieve and update
	The following example shows how to chain methods to retrieve and update

[norareidy]

I was thinking of specifying which fields / values you're updating (venue, ticketsSold), but agreed that this could be repetitive and I think it's fine as is!