Content/ID review feedback

Global changes

[x] "MongoDB" doesn't need to be monospaced
[ ] "microservice" and "service" seem to be used interchangeably throughout the guide - is it okay to go with just "service", or is "microservice" used specifically in certain instances?

What you’ll learn

[x] "You will learn how to build and test a simple microservice which manages the members of a crew using MongoDB." --> "You will learn how to use MongoDB to build and test a simple microservice that manages the members of a crew."
[x] For context, maybe give a one or two-sentence introduction to what MongoDB is in this section.
[x] "The microservice will respond to POST, GET, PUT, and DELETE requests made to the service to manipulate the database." --> "The microservice will respond to POST, GET, PUT, and DELETE requests that manipulate the database."
[x] "JSON-like" --> I'm not sure what "JSON-like" means. Just JSON? Or you could just say "...in the following format:"
[x] "This microservice connects to Mongo DB using Transport Layer Security (TLS) and injects a MongoDatabase instance into the service through a CDI producer." --> "This microservice connects to MongoDB by using Transport Layer Security (TLS) and injects a MongoDatabase instance into the service through a CDI producer."
[x] Should we spell out "CDI" on first mention?

Additional Prerequisites

[x] "Additional Prerequisites" --> "Additional prerequisites"
[x] "You will be using Docker to run an instance of MongoDB for a fast installation and setup. Install Docker by following the instructions on the official Docker documentation and start your Docker environment." --> "You will use Docker to run an instance of MongoDB for a fast installation and setup. Install Docker by following the instructions in the official Docker documentation, and start your Docker environment."

Try what you'll build

[ ] Move the "Try what you'll build" section so that it's nested under the "Getting started" section". Like in https://openliberty.io/guides/cdi-intro.html.

The TWYB section is nested under "Setting up MongoDB" because it is a pre-requisite to have the mongoDB running first in order to run the TWYB section. Should TWYB and "Setting up MongoDB" both be nested under "Getting started" or leave as is?

[x] Add a colon after "After you see the following message, your application server is ready" instead of a period.
- [x] PR: https://github.com/OpenLiberty/guides-common/pull/539

Setting up MongoDB

[x] Suggested first paragraph: "This guide uses Docker to run an instance of MongoDB. A multi-stage Dockerfile is provided for you. This Dockerfile uses the mongo image as the base image of the final stage and gathers the required configuration files. The resulting mongo image runs in a Docker container, and you must set up a new database for the microservice. Lastly, the truststore that's generated in the Docker image is copied from the container and placed into the Open Liberty server."
[x] Suggested second paragraph: "You can find more details and configuration options on the MongoDB website. For more information about the mongo image, see mongo in Docker Hub."
[x] Suggested third paragraph: "Run the following commands to use the Dockerfile to build the image, run the image in a Docker container, and map port 27017 from the container to your host machine:" --> Can we use a more specific term than "machine"? Maybe "computer"? IBM style advises against using "machine" wherever possible.
- [ ] It's used more as a technical keyword similar to "Virtual Machine". Also used in other guides in similar context.
[x] Suggested fourth paragraph: "The truststore that's created in the container needs to be added to the Open Liberty server so that the server can trust the certificate that MongoDB presents when they connect. Run the following command to copy the truststore.p12 file from the container to the start and finish directories on your host machine:" --> start and finish need to be monospaced - same thing as previous comment regarding "machine", can we use an alternative word?

Configuring the server

[ ] Move this section to after the "Performing CRUD operations" sections and before the "Running the application" section.
[x] The two paragraphs that begin "The features required to create the CDI producer..." and "Additionally, the Secure Sockets Layer..." spend a lot of time explaining what can be seen in the code. I also don't think we need the info related to how MongoDB previously worked. I'd suggest collapsing them down into one paragraph, something like, "The features that are required to create the CDI producer for MongoDB are cdi-2.0, ssl-1.0, mpConfig-1.4, and passwordUtilities-1.0, which are all specified in the featureManager element. The Secure Sockets Layer (SSL) context is configured in the server.xml file so that the application can connect to MongoDB with TLS. The keyStore element is configured to point to the truststore.p12 keystore file that was created in one of the earlier sections. The ssl element is configured to use the defaultKeyStore as the keystore and outboundTrustStore as the truststore." - The only hotspots I'd use in this paragraph are featureManager, keyStore, and ssl.
[x] "Using MicroProfile Config makes configuring the MongoDB driver simple since all the configuration can be set in one place and injected into the CDI producer." --> "Using MicroProfile Config makes configuring the MongoDB driver simple because all of the configuration can be set in one place and injected into the CDI producer."
[x] Suggested update for the paragraph that begins "Properties such as..." - "Properties such as the hostname, port, and database name for the running MongoDB instance are set in this file. Additionally, the user’s username and password are set here. For added security, the password was encoded by using the securityUtility encode command." - I also don't think that you need to hotspot any of these, as it seems very clear to me which is which in the short file.
[ ] "For reference on how the encoded password was generated, navigate to the target/liberty/wlp/bin/ directory in a separate command-line session and run the following command:" - Do users need to do this to complete the guide? If not, I'm thinking just linking to the securityUtility encode documentation is sufficient and this bit at the end can be taken out entirely.
- [ ] TODO: Confirm with Gilbert
  Using a CDI producer for MongoDB
[x] "With a CDI producer, you are no longer restricted to MongoDB 2.x versions, and can easily provide a MongoDatabase to your microservice." --> "With a CDI producer, you can easily provide a MongoDatabase to your microservice."
[x] Collapse the second and third paragraphs into one. Suggested update: "This class contains a producer method for the MongoClient, a producer method for the MongoDatabase that uses the MongoClient producer method, and a dispose method for the MongoClient. Before you create the methods, the values in the microprofile-config.properties file are injected into the MongoProducer class."
[x] The last three paragraphs of this section rely heavily on describing what's happening in the code, but they don't necessarily tell me why these things are important or need to happen. I suggest collapsing these three paragraphs down into two, something like, "The createMongo() method returns an instance of MongoClient. In this method, the username, database name, and decoded password are passed into the MongoCredential.createCredential() method to get an instance of MongoCredential. The JSSEHelper is used to get the SSLContext from the outboundSSLContext in the server.xml file. Then, a MongoClient instance is created and returned. - In this paragraph, only hotspot "createMongo()", "MongoCredential.createCredential()", "JSSEHelper", and the final instance of "MongoClient".

The createDB() method returns an instance of MongoDatabase. This method injects the MongoClient in its parameters and passes the database name into the MongoClient.getDatabase() method to get a MongoDatabase instance. The close() method is a cleanup function for the MongoClient that closes the connection to the MongoDB instance." - In this paragraph, only hotspot "createDB()", "MongoClient.getDatabase()", and "close()". Then, add a sentence or two to each paragraph that explains why these points that we're highlighting are important.

Performing CRUD operations

[x] Suggested first paragraph (collapse one and two together): You are going to implement the basic CRUD operations, which are create, read, update, and delete. The com.mongodb.client and com.mongodb.client.result packages are used to help implement these CRUD operations for the microservice. For more information about these packages, see the com.mongodb.client and com.mongodb.client.result Javadoc. For more information about creating a RESTful service with JAX-RS, JSON-B, and Open Liberty, see the Creating a RESTful web service guide." - Don't use monospacing for CRUD
[x] I'd collapse the last three paragraphs into two. Suggested update: "In this class, a Validator is used to validate a CrewMember before the database is updated. The CDI producer is used to inject a MongoDatabase into the CrewService class. - Only hotspot "Validator", "CrewMember", and "MongoDatabase"

Go to the http://localhost:9080/openapi/ui/ URL to see the OpenAPI UI that provides API documentation and a client to test the API endpoints you'll create."

Implementing Create operation

[x] Change title to "Implementing the create operation"
[x] Don't monospace "create"
[ ] Is it supposed to be "TDocument" as the type?
[x] Suggested update for the first paragraph (I took out TDocument): The add() method handles the implementation of the create operation. An instance of MongoCollection is retrieved with the MongoDatabase.getCollection() method. The Document type parameter specifies that the Document type is used to store data in the MongoCollection. Each crew member is converted into a document, and the MongoCollection.insertOne() method inserts a new crew member document.
[x] Suggested second paragraph: From the OpenAPI UI, test the create operation at the POST /api/crew endpoint by using the following code as the request body:
[x] Suggested third paragraph: This request creates a new document in the Crew collection with a name of Member1, rank of Officer, and crew ID of 000001.
[x] Suggested fourth paragraph: You will receive a response that contains the JSON object of the new crew member, as shown in the following example:
[x] Suggested fifth paragraph: The <> that you receive is a unique identifier in the collection. Save this value for future commands.

Implementing Read operation

[x] Change title to "Implementing the read operation"
[x] Suggested first paragraph: The retrieve() method handles the implementation of the read operation. The Crew collection is retrieved with the MongoDatabase.getCollection() method. Then, the MongoCollection.find() method retrieves a FindIterable object. This object is iterable for all the crew members documents in the collection, so each crew member document is concatenated into a String array and returned.
[x] Suggested second paragraph (collapse the second and third into a single paragraph): From the OpenAPI UI, test the read operation at the GET /api/crew endpoint. This request gets all crew member documents from the collection.
[x] Suggested third paragraph: You will receive a response that contains an array of all the members in your crew. The response might include crew members that were created in the Try what you’ll build section:

Implementing Update operation

[x] Change title to "Implementing the update operation"
[x] Suggested first paragraph: The update() method handles the implementation of the update operation. After Crew collection is retrieved, a document is created with the specified object id to query the collection. Next, a new crew member document is created with the updated configuration. The MongoCollection.replaceOne() method is called with the query and new crew member document, which updates all matching queries with the new document. Because the object id is unique in the collection, only one document is updated. The MongoCollection.replaceOne() method also returns an UpdateResult, which determines how many documents matched the query. If the match count is zero, then the object id doesn't exist. - don't hotspot the second instance of "Document" or the second instance of "MongoCollection.replaceOne() "
[x] Suggested second paragraph: From the OpenAPI UI, test the update operation at the PUT /api/crew/{id} endpoint, where the {id} parameter is the <<ID>> that you saved from the create operation. Use the following code as the request body:
[x] Suggested third paragraph: This request updates the rank of the crew member that you created from Officer to Captain.
[x] Suggested fourth paragraph: You will receive a response that contains the JSON object of the updated crew member, as shown in the following example:

Implementing Delete operation

[x] Change title to "Implementing the delete operation"
[x] Suggested first paragraph: The remove() method handles the implementation of the delete operation. After the Crew collection is retrieved, a document is created with the specified object id to query the collection. Because the object id is unique in the collection, only one document is deleted. After the document is deleted, the MongoCollection.deleteOne() method returns a DeleteResult, which determines how many documents were deleted. If the deleted count is zero, then the object id doesn't exist.
[x] Suggested second paragraph (collapse two and three into a single paragraph): From the OpenAPI UI, test the delete operation at the DELETE/api/crew/{id} endpoint, where the {id} parameter is the <<ID>> that you saved from the create operation. This request removes the document that contains the specified crew member object id from the collection. You will receive a response that contains the object id of the deleted crew member:
[x] Suggested third paragraph: You will receive a response that contains the object id of the deleted crew member, as shown in the following example:

Running the application

[x] Suggested update for the second paragraph: You can check out the microservice that you created by going to the http://localhost:9080/mongo/ URL after you see a message similar to the following example:

The application guide-mongodb-intro updated in 1.023 seconds.

Testing the application

[x] First paragraph update: Next, you'll create integrated tests to ensure that the basic operations that you implemented function correctly.
[x] Third paragraph update: The following test cases are included in this class:

Running the tests

[x] Suggested update of first sentence: Because you started Open Liberty in dev mode, press the enter/return key to run the tests. - monospace "enter/return"
- [ ] PR: https://github.com/OpenLiberty/guides-common/pull/542
[x] Second sentence: You'll see the following output:

Tearing down the environment

[x] Second sentence: Then, run the following commands to stop and remove the mongo-guide container and to remove the mongo-sample and mongo images.

Nice work! Where to next?

[x] Suggested update: Nice work! You learned how to access MongoDB by using Contexts and Dependency Injection (CDI), and configure MongoDB with MicroProfile Config.

OpenLiberty / guide-mongodb-intro