diff --git a/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/chain-search-query-helpers-to-narrow-search-results.english.md b/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/chain-search-query-helpers-to-narrow-search-results.english.md
index c37e4bb9dc..f4005d10f2 100644
--- a/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/chain-search-query-helpers-to-narrow-search-results.english.md
+++ b/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/chain-search-query-helpers-to-narrow-search-results.english.md
@@ -6,13 +6,12 @@ challengeType: 2
## Description
-If you don’t pass the callback as the last argument to Model.find() (or to the other search methods), the query is not executed. You can store the query in a variable for later use. This kind of object enables you to build up a query using chaining syntax. The actual db search is executed when you finally chain the method .exec(). Pass your callback to this last method. There are many query helpers, here we’ll use the most ‘famous’ ones.
-Find people who like "burrito". Sort them by name, limit the results to two documents, and hide their age. Chain .find(), .sort(), .limit(), .select(), and then .exec(). Pass the done(err, data) callback to exec().
+If you don’t pass the callback as the last argument to Model.find() (or to the other search methods), the query is not executed. You can store the query in a variable for later use. This kind of object enables you to build up a query using chaining syntax. The actual db search is executed when you finally chain the method .exec(). You always need to pass your callback to this last method. There are many query helpers, here we’ll use the most ‘famous’ ones.
## Instructions
-
+Find people who like burrito. Sort them by name, limit the results to two documents, and hide their age. Chain .find(), .sort(), .limit(), .select(), and then .exec(). Pass the done(err, data) callback to exec().
## Tests
diff --git a/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/create-a-model.english.md b/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/create-a-model.english.md
index 4c7f888733..2f1ae255f7 100644
--- a/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/create-a-model.english.md
+++ b/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/create-a-model.english.md
@@ -6,32 +6,38 @@ challengeType: 2
## Description
+CRUD Part I - CREATE
+
First of all we need a Schema. Each schema maps to a MongoDB collection. It defines the shape of the documents within that collection.
Schemas are building block for Models. They can be nested to create complex models, but in this case we’ll keep things simple.
A model allows you to create instances of your objects, called documents.
-Create a person having this prototype :
-- Person Prototype -
---------------------
-name : string [required]
-age : number
-favoriteFoods : array of strings (*)
-Use the mongoose basic schema types. If you want you can also add
-more fields, use simple validators like required or unique,
-and set default values. See the mongoose docs.
-[C]RUD Part I - CREATE
-Note: Glitch is a real server, and in real servers the interactions with the db happen in handler functions. These function are executed when some event happens (e.g. someone hits an endpoint on your API). We’ll follow the same approach in these exercises. The done() function is a callback that tells us that we can proceed after completing an asynchronous operation such as inserting, searching, updating or deleting. It’s following the Node convention and should be called as done(null, data) on success, or done(err) on error.
-Warning - When interacting with remote services, errors may occur !
-/* Example */
-var someFunc = function(done) {
- //... do something (risky) ...
- if(error) return done(error);
- done(null, result);
-};
+
+Glitch is a real server, and in real servers the interactions with the db happen in handler functions. These function are executed when some event happens (e.g. someone hits an endpoint on your API). We’ll follow the same approach in these exercises. The done() function is a callback that tells us that we can proceed after completing an asynchronous operation such as inserting, searching, updating or deleting. It’s following the Node convention and should be called as done(null, data) on success, or done(err) on error.
+Warning - When interacting with remote services, errors may occur!
+
+/* Example */
+var someFunc = function(done) {
+ //... do something (risky) ...
+ if(error) return done(error);
+ done(null, result);
+};
+
## Instructions
+Create a person having this prototype :
+
+- Person Prototype -
+--------------------
+name : string [required]
+age : number
+favoriteFoods : array of strings (*)
+
+Use the mongoose basic schema types. If you want you can also add
+more fields, use simple validators like required or unique,
+and set default values. See the mongoose docs.
## Tests
diff --git a/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/create-and-save-a-record-of-a-model.english.md b/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/create-and-save-a-record-of-a-model.english.md
index 933546e352..3d70a5c6b6 100644
--- a/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/create-and-save-a-record-of-a-model.english.md
+++ b/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/create-and-save-a-record-of-a-model.english.md
@@ -6,17 +6,19 @@ challengeType: 2
## Description
-Create a document instance using the Person constructor you built before. Pass an object to the constructor with the fields name, age, and favoriteFoods. Their types must conform to the ones in the Person Schema. Then call the method document.save() on the returned document instance. Pass it a callback using the Node convention you saw before. This is a common pattern, all the following CRUD methods take a callback function like this as the last argument.
-/* Example */
-// ...
-person.save(function(err, data) {
-// ...do your stuff here...
-});
+In this challenge you will have to create and save a record of a model.
## Instructions
-
+Create a document instance using the Person constructor you built before. Pass to the constructor an object having the fields name, age, and favoriteFoods. Their types must be conformant to the ones in the Person Schema. Then call the method document.save() on the returned document instance. Pass to it a callback using the Node convention. This is a common pattern, all the following CRUD methods take a callback function like this as the last argument.
+
+/* Example */
+// ...
+person.save(function(err, data) {
+ // ...do your stuff here...
+});
+
## Tests
diff --git a/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/create-many-records-with-model.create.english.md b/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/create-many-records-with-model.create.english.md
index 367d5634c2..3eade92ee2 100644
--- a/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/create-many-records-with-model.create.english.md
+++ b/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/create-many-records-with-model.create.english.md
@@ -6,12 +6,12 @@ challengeType: 2
## Description
-Sometimes you need to create many instances of your models, e.g. when seeding a database with initial data. Model.create() takes an array of objects like [{name: 'John', ...}, {...}, ...] as the first argument, and saves them all in the db. Create many people with Model.create(), using the function argument arrayOfPeople.
+Sometimes you need to create many instances of your models, e.g. when seeding a database with initial data. Model.create() takes an array of objects like [{name: 'John', ...}, {...}, ...] as the first argument, and saves them all in the db.
## Instructions
-
+Create many people with Model.create(), using the function argument arrayOfPeople.
## Tests
diff --git a/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/delete-many-documents-with-model.remove.english.md b/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/delete-many-documents-with-model.remove.english.md
index 9c363b6f10..5f414da7ac 100644
--- a/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/delete-many-documents-with-model.remove.english.md
+++ b/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/delete-many-documents-with-model.remove.english.md
@@ -6,13 +6,13 @@ challengeType: 2
## Description
-Model.remove() is useful to delete all the documents matching given criteria. Delete all the people whose name is “Mary”, using Model.remove(). Pass it to a query document with the “name” field set, and of course a callback.
-Note: Model.remove() doesn’t return the deleted document, but a JSON object containing the outcome of the operation, and the number of items affected. Don’t forget to pass it to the done() callback, since we use it in tests.
+Model.remove() is useful to delete all the documents matching given criteria.
## Instructions
-
+Delete all the people whose name is “Mary”, using Model.remove(). Pass it to a query document with the name field set, and of course a callback.
+Note: The Model.remove() doesn’t return the deleted document, but a JSON object containing the outcome of the operation, and the number of items affected. Don’t forget to pass it to the done() callback, since we use it in tests.
## Tests
diff --git a/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/delete-one-document-using-model.findbyidandremove.english.md b/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/delete-one-document-using-model.findbyidandremove.english.md
index 10dc2e7243..d8da165f54 100644
--- a/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/delete-one-document-using-model.findbyidandremove.english.md
+++ b/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/delete-one-document-using-model.findbyidandremove.english.md
@@ -6,7 +6,7 @@ challengeType: 2
## Description
-Delete one person by her _id. You should use one of the methods findByIdAndRemove() or findOneAndRemove(). They are like the previous update methods. They pass the removed document to the cb. As usual, use the function argument personId as search key.
+Delete one person by the person's _id. You should use one of the methods findByIdAndRemove() or findOneAndRemove(). They are like the previous update methods. They pass the removed document to the cb. As usual, use the function argument personId as the search key.
## Instructions
diff --git a/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/install-and-set-up-mongoose.english.md b/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/install-and-set-up-mongoose.english.md
index e2434ac71f..4e2513e58d 100644
--- a/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/install-and-set-up-mongoose.english.md
+++ b/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/install-and-set-up-mongoose.english.md
@@ -6,10 +6,11 @@ challengeType: 2
## Description
-Add mongodb and mongoose to the project’s package.json. Then require mongoose. Store your mLab database URI in the private .env file as MONGO_URI. Connect to the database using mongoose.connect()
+Add mongodb and mongoose to the project’s package.json. Then require mongoose. Store your mLab database URI in the private .env file as MONGO_URI. Connect to the database using mongoose.connect(<Your URI>)
## Instructions
+Add mongodb and mongoose to the project’s package.json. Then require mongoose. Store your mLab database URI in the private .env file as MONGO_URI. Connect to the database using mongoose.connect(<Your URI>)
diff --git a/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/perform-classic-updates-by-running-find-edit-then-save.english.md b/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/perform-classic-updates-by-running-find-edit-then-save.english.md
index daca54e180..f28fc035ee 100644
--- a/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/perform-classic-updates-by-running-find-edit-then-save.english.md
+++ b/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/perform-classic-updates-by-running-find-edit-then-save.english.md
@@ -6,13 +6,14 @@ challengeType: 2
## Description
-In the good old days this was what you needed to do if you wanted to edit a document and be able to use it somehow e.g. sending it back in a server response. Mongoose has a dedicated updating method : Model.update(). It is bound to the low-level mongo driver. It can bulk edit many documents matching certain criteria, but it doesn’t send back the updated document, only a ‘status’ message. Furthermore it makes model validations difficult, because it just directly calls the mongo driver.
-Find a person by _id ( use any of the above methods ) with the parameter personId as search key. Add “hamburger” to the list of her favoriteFoods (you can use Array.push()). Then - inside the find callback - save() the updated Person.
-[*] Hint: This may be tricky if in your Schema you declared favoriteFoods as an Array, without specifying the type (i.e. [String]). In that casefavoriteFoods defaults to Mixed type, and you have to manually mark it as edited using document.markModified('edited-field'). (http://mongoosejs.com/docs/schematypes.html - #Mixed )
+In the good old days this was what you needed to do if you wanted to edit a document and be able to use it somehow e.g. sending it back in a server response. Mongoose has a dedicated updating method : Model.update(). It is bound to the low-level mongo driver. It can bulk edit many documents matching certain criteria, but it doesn’t send back the updated document, only a ‘status’ message. Furthermore it makes model validations difficult, because it just directly calls the mongo driver.
## Instructions
+Find a person by _id ( use any of the above methods ) with the parameter personId as search key. Add "hamburger" to the list of the person's favoriteFoods (you can use Array.push()). Then - inside the find callback - save() the updated Person.
+
+Note: This may be tricky, if in your Schema, you declared favoriteFoods as an Array, without specifying the type (i.e. [String]). In that casefavoriteFoods defaults to Mixed type, and you have to manually mark it as edited using document.markModified('edited-field'). See Mongoose documentation at https://mongoosejs.com/docs/schematypes.html#Mixed
diff --git a/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/perform-new-updates-on-a-document-using-model.findoneandupdate.english.md b/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/perform-new-updates-on-a-document-using-model.findoneandupdate.english.md
index 58d37ea5df..a47b0fe375 100644
--- a/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/perform-new-updates-on-a-document-using-model.findoneandupdate.english.md
+++ b/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/perform-new-updates-on-a-document-using-model.findoneandupdate.english.md
@@ -6,14 +6,13 @@ challengeType: 2
## Description
-Recent versions of mongoose have methods to simplify documents updating. Some more advanced features (i.e. pre/post hooks, validation) behave differently with this approach, so the Classic method is still useful in many situations. findByIdAndUpdate() can be used when searching by Id.
-Find a person by Name and set her age to 20. Use the function parameter personName as search key.
-Hint: We want you to return the updated document. To do that you need to pass the options document { new: true } as the 3rd argument to findOneAndUpdate(). By default these methods return the unmodified object.
+Recent versions of mongoose have methods to simplify documents updating. Some more advanced features (i.e. pre/post hooks, validation) behave differently with this approach, so the Classic method is still useful in many situations. findByIdAndUpdate() can be used when searching by Id.
## Instructions
-
+Find a person by Name and set the person's age to 20. Use the function parameter personName as search key.
+Note: You should return the updated document. To do that you need to pass the options document { new: true } as the 3rd argument to findOneAndUpdate(). By default these methods return the unmodified object.
## Tests
diff --git a/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/use-model.find-to-search-your-database.english.md b/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/use-model.find-to-search-your-database.english.md
index 03e13a2043..b9ac6d8bdc 100644
--- a/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/use-model.find-to-search-your-database.english.md
+++ b/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/use-model.find-to-search-your-database.english.md
@@ -6,8 +6,8 @@ challengeType: 2
## Description
-Find all the people having a given name, using Model.find() -> [Person]
-In its simplest usage, Model.find() accepts a query document (a JSON object ) as the first argument, then a callback. It returns an array of matches. It supports an extremely wide range of search options. Check it in the docs. Use the function argument personName as search key.
+Find all the people having a given name, using Model.find() -> [Person]
+In its simplest usage, Model.find() accepts a query document (a JSON object) as the first argument, then a callback. It returns an array of matches. It supports an extremely wide range of search options. Check it in the docs. Use the function argument personName as search key.
## Instructions
diff --git a/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/use-model.findbyid-to-search-your-database-by-id.english.md b/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/use-model.findbyid-to-search-your-database-by-id.english.md
index ce60660e45..118f77e4c0 100644
--- a/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/use-model.findbyid-to-search-your-database-by-id.english.md
+++ b/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/use-model.findbyid-to-search-your-database-by-id.english.md
@@ -6,12 +6,12 @@ challengeType: 2
## Description
-When saving a document, mongodb automatically adds the field _id, and set it to a unique alphanumeric key. Searching by _id is an extremely frequent operation, so mongoose provides a dedicated method for it. Find the (only!!) person who has the given _id using Model.findById() -> Person. Use the function argument personId as search key.
+When saving a document, mongodb automatically adds the field _id, and set it to a unique alphanumeric key. Searching by _id is an extremely frequent operation, so mongoose provides a dedicated method for it.
## Instructions
-
+Find the (only!!) person having a given _id, using Model.findById() -> Person. Use the function argument personId as the search key.
## Tests
diff --git a/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/use-model.findone-to-return-a-single-matching-document-from-your-database.english.md b/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/use-model.findone-to-return-a-single-matching-document-from-your-database.english.md
index ec0d5c1e3c..0c88652feb 100644
--- a/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/use-model.findone-to-return-a-single-matching-document-from-your-database.english.md
+++ b/curriculum/challenges/english/05-apis-and-microservices/mongodb-and-mongoose/use-model.findone-to-return-a-single-matching-document-from-your-database.english.md
@@ -6,12 +6,12 @@ challengeType: 2
## Description
-Model.findOne() behaves like .find(), but it returns only one document (not an array), even if there are multiple items. It is especially useful when searching by properties that you have declared as unique. Find just one person which has a certain food in her favorites, using Model.findOne() -> Person. Use the function argument food as search key.
+Model.findOne() behaves like .find(), but it returns only one document (not an array), even if there are multiple items. It is especially useful when searching by properties that you have declared as unique.
## Instructions
-
+Find just one person which has a certain food in the person's favorites, using Model.findOne() -> Person. Use the function argument food as search key.
## Tests