DOCSP-34122: Integrations guide #511

norareidy · 2024-01-24T20:32:45Z

Pull Request Info

JIRA - https://jira.mongodb.org/browse/DOCSP-34122
Staging - https://preview-mongodbnorareidy.gatsbyjs.io/java/DOCSP-34122-common-frameworks/integrations/

Self-Review Checklist

Is this free of any warnings or errors in the RST?
Did you run a spell-check?
Did you run a grammar-check?
Are all the links working?
Are the facets and meta keywords accurate?

…n-frameworks

ccho-mongodb

Thanks for picking up this task. I think the framework and tool summaries demonstrate a good grasp of the information.

I think most of my comments apply to the level of detail and organization of the information. The subheadings indicated deeper information on incorporating the frameworks/tools into an application, but weren't detailed enough to perform that action. I'd recommend formulating the learning objectives of the page and finding the right level of detail that could be made consistent across the headings.

I think it would also be helpful to avoid jargon (including classnames and method names, especially since those can change without notice) and to present information concisely.

source/index.txt

source/integrations.txt

ccho-mongodb · 2024-02-12T21:04:50Z

source/integrations.txt

+
+.. note::
+
+   MongoDB does not own the tools included on this page.


Suggestion:
I think readers might want more specific information than ownership, such as whether MongoDB provides support for them, runs test suites to check for compatibility with them, etc. I think it could also be "important" since it could be essential information for audiences that might have some assumptions around support/compatibility.
I don't know the specifics, but I had added a comment in the ticket that they are not "official MongoDB partners" which could be one of the pieces of information surfaced in this callout.

E.g.
"These integrations are not official MongoDB partners. explain the support policy
(or lack thereof) here"

source/integrations.txt

ccho-mongodb

LGTM. Thanks for the updates, the consistent structure helps locate info quickly!

A couple minor items to address in addition to the support policy details.

ccho-mongodb · 2024-02-29T05:51:13Z

source/integrations.txt

+You can use Spring Data MongoDB's template API to perform CRUD operations on MongoDB data.
+Additionally, the MongoDB converter allows you to map domain objects to MongoDB documents,
+and the GridFS template provides access to MongoDB's GridFS filesystem. 


Suggestion:
No change necessary, but I think this could be easier to find the information for each feature if presented as a list.

ccho-mongodb · 2024-02-29T05:56:17Z

source/integrations.txt

-Quarkus also supports a variety of application styles, including HTTP microservices,
-reactive applications, and serverless functions.
+The `Quarkus <https://quarkus.io/>`__ Java framework supports the development of microservices
+and serverless systems. Quarkus is native to `Kubernetes <https://kubernetes.io/>`__, a platform


Suggestion:

I think "serverless applications" is more commonly used and could replace the term "serverless systems".

ccho-mongodb · 2024-02-29T06:09:37Z

source/integrations.txt

+MongoDB databases by using a Spring-based programming model. For instructions on using
+Spring Data MongoDB to build an application and interact with MongoDB, see the 
+`Accessing Data with MongoDB <https://spring.io/guides/gs/accessing-data-mongodb>`__ guide in
+the Spring documentation.


Suggestion:
Related to this comment, I think the placement of "how to use this" ("For instructions...") between the "what it is" and "what are the features" parts of the information can interrupt the flow.

I think ordering the info the following way could flow better:

"What it is"
"What are the features"
"How to use this"

Applies to all the sections.

ccho-mongodb · 2024-02-29T06:11:56Z

source/integrations.txt

-can create compact Panache entities to represent MongoDB documents. Several annotations,
-including ``@MongoEntity``, ``@BsonProperty``, and ``@BsonIgnore``, allow for
-customized mapping between entities and MongoDB documents.
+Use the MongoDB client extension to access the following features:


Suggestion:

I think it could be helpful to stay consistent in each section with whether imperative mood (either using it or not using it) is used when presenting the features in each section. I think either way (Spring Data "You can use..." or Quarkus "Use the ...") works.

ccho-mongodb · 2024-02-29T06:16:15Z

source/integrations.txt

+the Spring documentation.
+
+You can use Spring Data MongoDB's template API to perform CRUD operations on MongoDB data.
+Additionally, the MongoDB converter allows you to map domain objects to MongoDB documents,


Issue:
From the style guide entry on terminology:

Use allow only when discussing permission. Avoid using allow to imply that a program, feature, or product permits a user to do something. Use you can instead. Enables is also acceptable.

Suggestion:

I think replacing "allows" with "enables" would follow the style guide guidance.

Applies to all instances.

ashni-mehta · 2024-04-24T16:33:06Z

source/integrations.txt

+Spring Data MongoDB enables you to access MongoDB databases by using a Spring-based programming
+model. 
+
+You can use Spring Data MongoDB's template API to perform the following actions:


Spring Data supports a bunch of MongoDB capabilities outside of CRUD. Could we call out that Atlas Search is supported, as well as CSFLE?

ashni-mehta

Added a few comments, mostly in the Spring section.

ashni-mehta · 2024-04-24T20:39:40Z

source/integrations.txt

+
+.. important::
+
+   The integrations on this page are not official MongoDB partners.


Perhaps we could change language here slightly to say something like:

"The integrations on this page are not officially developed by MongoDB" or
"The integrations on this page are not developed by official MongoDB partners" or
"The open-source integrations listed below are all community-developed and maintained."

To clarify that the integrations themselves are not the partners, but rather are not developed by us / our partners?

ashni-mehta · 2024-04-24T20:42:24Z

source/integrations.txt

+- Access MongoDB's GridFS filesystem using the GridFS template
+
+For instructions on using Spring Data MongoDB to build an application and interact with MongoDB, see the 
+`Accessing Data with MongoDB <https://spring.io/guides/gs/accessing-data-mongodb>`__ guide in


I don't know how up to date this information is given that there's an open issue asking to upgrade to the latest version of the Spring documentation. Could we link to this page instead in the reference documentation?

[https://docs.spring.io/spring-data/mongodb/reference/mongodb/getting-started.html]

ashni-mehta

LGTM! Thanks @norareidy !

This reverts commit b52c017.

* first draft * edits * page format, toc * edits, ownership * wording * rewording, edits * more wording changes * moving location on TOC * most CC feedback * wording * more wording * CC feedback pt 2 * edits * build * AM feedback * build log fix * Revert "build log fix" This reverts commit b52c017. (cherry picked from commit eafcda6)

norareidy added 10 commits January 24, 2024 15:29

first draft

ed8d8da

edits

59cc15d

page format, toc

379d66f

Merge remote-tracking branch 'upstream/master' into DOCSP-34122-commo…

55b9a3a

…n-frameworks

edits, ownership

f28f40b

wording

1712887

rewording, edits

77975a3

more wording changes

6d0c401

moving location on TOC

7c18184

Merge remote-tracking branch 'upstream/master' into DOCSP-34122-commo…

47aed58

…n-frameworks

ccho-mongodb suggested changes Feb 12, 2024

View reviewed changes

norareidy added 3 commits February 28, 2024 10:07

most CC feedback

65d6485

wording

1d4efdc

more wording

9e698ab

ccho-mongodb approved these changes Feb 29, 2024

View reviewed changes

norareidy added 2 commits February 29, 2024 15:51

CC feedback pt 2

175646a

edits

c89160c

ashni-mehta self-requested a review March 12, 2024 15:17

build

7e63857

ashni-mehta reviewed Apr 24, 2024

View reviewed changes

ashni-mehta suggested changes Apr 24, 2024

View reviewed changes

AM feedback

bed5e63

norareidy requested a review from ashni-mehta April 25, 2024 15:24

ashni-mehta approved these changes Apr 25, 2024

View reviewed changes

norareidy added 2 commits April 25, 2024 13:31

build log fix

b52c017

Revert "build log fix"

06a8563

This reverts commit b52c017.

norareidy merged commit eafcda6 into mongodb:master Apr 25, 2024

norareidy deleted the DOCSP-34122-common-frameworks branch April 25, 2024 17:35


		.. note::

		MongoDB does not own the tools included on this page.


		.. important::

		The integrations on this page are not official MongoDB partners.

DOCSP-34122: Integrations guide #511

DOCSP-34122: Integrations guide #511

Uh oh!

Conversation

norareidy commented Jan 24, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Info

Self-Review Checklist

Uh oh!

ccho-mongodb left a comment

Choose a reason for hiding this comment

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!

Uh oh!

Uh oh!

ccho-mongodb 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!

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!

ashni-mehta 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!

ashni-mehta left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

norareidy commented Jan 24, 2024 •

edited

Loading