DOCSP-37618: Usage Examples landing page #2767

norareidy · 2024-03-12T16:23:08Z

JIRA - https://jira.mongodb.org/browse/DOCSP-37618
Staging - https://preview-mongodbnorareidy.gatsbyjs.io/laravel/DOCSP-37618-staging/usage-examples/

Checklist

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

ccho-mongodb

Looks pretty good! I'd like to take another look after the issues are resolved since they might change the content significantly.

docs/usage-examples.txt

ccho-mongodb · 2024-03-13T14:19:23Z

docs/usage-examples.txt

+Follow this tutorial to set up your MongoDB deployment with the sample data and run the
+example code in your development environment. Before performing the following actions,
+ensure that you create an Atlas account and deploy a cluster. For information about setting
+up an account and a cluster, see the :atlas:`Get Started with Atlas Guide
+</getting-started/#atlas-getting-started>`.


Issue:

I think the description of the procedure/steps is currently inaccurate. When reading the first sentence "Follow this tutorial to set up your MongoDB deployment with sample data and run the sample code...", I expected the tutorial to explain that part. However, the procedure/steps includes the prerequisite of the quick start guide which includes setup of the MongoDB deployment with sample data and how to add and run the code.

I think the step in the tutorial about running the usage example code is inaccurate since it omits information about viewing it in the browser.

Suggestion:

I think keeping the description of the steps and the procedure/steps aligned would be helpful. I also think this page should delegate some of the explanation of how to run them to the specific usage example since the procedure might differ depending on the operation.

E.g.

"You can run the usage examples from Laravel web application and MongoDB Atlas cluster that you set up in the :ref:laravel-quick-start guide. Ensure that your application and cluster meet the following requirements:
...

To run the example controller code and view the results, follow the instructions on the usage example page.
"

Let me know if you need any help with filling out the details.

Thanks for this detailed comment; I think I made all the changes you requested, let me know if it looks alright

docs/usage-examples.txt

ccho-mongodb

LGTM!
Added a couple suggestions that I think could make the procedure easier to follow.

ccho-mongodb · 2024-03-13T19:28:51Z

docs/usage-examples.txt

+application meets the following requirements:
+
+- Connects to the ``movies`` collection in the Atlas sample datasets
+- Contains the ``MovieController.php`` and ``browse_movies.blade.php`` files


Suggestion:

I think it could be easier to verify the requirements as Laravel web app components rather than existence of the collection and files. I think it's also missing mention of the API controller (used for storing data - see https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/quick-start/write-data/). E.g.

"... application contains the following components:"

Configuration to use an Atlas cluster that contains the sample datasets

Movie model configured to use the MongoDB database

Movie view that lists the results

HTTP and API controller endpoints for displaying and storing Movie data
"

ccho-mongodb · 2024-03-13T19:43:43Z

docs/usage-examples.txt

+Then, follow this tutorial to add the usage example code to your Laravel application and view 
+the expected results.
+
+.. procedure::
+   :style: connected
+
+   .. step:: Add the Controller Code to Your Application
+
+      Copy the example code from the :guilabel:`Controller File Code` tab on the usage example
+      page and paste it into the ``MovieController.php`` file.
+
+   .. step:: Add the View Code to Your Application
+
+      Copy the example code from the :guilabel:`View File Code` tab on the usage example page and
+      paste it into the ``browse_movies.blade.php`` file.
+
+   .. step:: Run the Usage Example Code
+
+      To run the example controller code and view the results, follow the instructions on the
+      usage example page.


Suggestion:

I think presenting this information might not make sense before a reader gets the chance to see a Usage Example page. As mentioned in a previous comment, it should delegate some of the explanation to the specific usage examples since they may differ depending on the operation.

Start with information on when this applies, e.g.
"
Each Usage Example page features example code in the Controller File Code and View File Code tabs that you can copy and paste into your Laravel application.

Unless otherwise specified, you can add Usage Example sample code to your application by performing the following actions:

Add the code from the Controller File Code tab to your MovieController.php file in the ... directory

Add the code from the View File Code tab to your browse_movies.blade.php file in the ... directory.

Follow the instructions on the Usage Example page to run the code and view the output.
"

Ah okay, so including tutorial steps doesn't seem necessary; changed

…-landing

GromNaN

I don't get the point of this page.

GromNaN · 2024-03-15T14:11:08Z

docs/usage-examples.txt

+you set up in the :ref:`laravel-quick-start` guide. After completing the Quick Start, ensure
+that your application meets the following requirements:
+
+- Configuration to use an Atlas cluster that contains the sample datasets


How a beginner can check all this requirements?

I added a tip directive that links to each corresponding Quick Start step, so the user can click on those for more details on how to fulfill the requirements.

docs/usage-examples.txt

norareidy · 2024-03-15T15:31:41Z

I don't get the point of this page.

In all the drivers docs, we have a usage example landing page that explains how to run the code examples. Then, all the individual usage examples are linked out from that page. Here’s the Rust driver usage example landing page and a usage example, for instance. So the structure would be similar in this case. Hopefully that clarifies the point of this page a bit!

GromNaN · 2024-03-26T18:09:54Z

.github/workflows/merge-up.yml

@@ -27,4 +27,4 @@ jobs:
        uses: alcaeus/automatic-merge-up-action@main
        with:
          ref: ${{ github.ref_name }}
-          branchNamePattern: '<major>.<minor>'
+          branchNamePattern: '<major>.<minor>'


The newline at end of file must be reverted.

Ah this was unintentional, fixed

norareidy added 4 commits March 12, 2024 12:22

DOCSP-37618: Usage Examples landing page

44a0f86

fix refs

afc83e1

update TOC

f97fbb3

format fix

79a19c0

ccho-mongodb suggested changes Mar 13, 2024

View reviewed changes

norareidy added 4 commits March 13, 2024 15:00

CC feedback

6edfb45

remove info

2885cc5

add back

301ff74

typo

f08b2be

norareidy requested a review from ccho-mongodb March 13, 2024 19:14

ccho-mongodb previously approved these changes Mar 13, 2024

View reviewed changes

CC feedback 2

e3af41b

norareidy dismissed ccho-mongodb’s stale review via e3af41b March 14, 2024 16:01

norareidy added 2 commits March 14, 2024 12:04

Merge remote-tracking branch 'upstream/4.1' into DOCSP-37618-usage-ex…

6b0e08f

…-landing

add section toc

fc7970d

norareidy marked this pull request as ready for review March 14, 2024 17:25

norareidy requested a review from a team as a code owner March 14, 2024 17:25

norareidy requested a review from GromNaN March 14, 2024 17:25

GromNaN reviewed Mar 15, 2024

View reviewed changes

norareidy added 9 commits March 18, 2024 11:20

feedback, removing tabs

9034064

workflow file

ab90497

edits

9e0b2dc

fix

7544220

more CC feedback

fdca1ba

run -> use

7aa61f9

changes to running instructions

8c3905c

turn back into steps

245412f

small fixes

e92f51b

GromNaN approved these changes Mar 21, 2024

View reviewed changes

norareidy added 4 commits March 21, 2024 13:31

more reworking

2fe5eb9

reword

9faa171

reworking

d2d9c9c

feedback

7ad6bdc

GromNaN added the docs label Mar 25, 2024

GromNaN changed the base branch from 4.1 to docs-rewrite March 25, 2024 16:26

GromNaN changed the base branch from docs-rewrite to 4.1 March 25, 2024 16:59

GromNaN requested changes Mar 26, 2024

View reviewed changes

norareidy added 4 commits March 28, 2024 16:43

newline

27dd0dd

remove file

9912b50

edits

64afec5

fix

fc06d29

caitlindavey requested a review from GromNaN April 1, 2024 18:47

GromNaN approved these changes Apr 2, 2024

View reviewed changes

norareidy merged commit 9a616f9 into mongodb:4.1 Apr 3, 2024

norareidy deleted the DOCSP-37618-usage-ex-landing branch April 3, 2024 14:24

DOCSP-37618: Usage Examples landing page #2767

DOCSP-37618: Usage Examples landing page #2767

Uh oh!

Conversation

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

Uh oh!

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!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

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!

GromNaN 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!

norareidy commented Mar 15, 2024

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

norareidy commented Mar 12, 2024 •

edited

Loading