Proposed rewrite to "Creating Microsoft Azure Virtual Machines for NGINX Open Source and F5 NGINX Plus" #608

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Open

jawfu-M wants to merge 62 commits into nginx:main from jawfu-M:Update-docs-issue147

jawfu-M commented May 27, 2025 •

edited by mjang

Loading

NOTE: this is a rewrite only. No technical changes.

The original documentation was slightly difficult to read and follow. It had complex sentences and paragraphs that scored 14 on the Hemmingway app. Some constructs were conflicting or confusing, which took longer to understand.

I improved the document’s readability and clarity, making it accessible to a wider, non-expert audience. Here’s how:

Rewrote complex paragraphs graded at 14 to achieve Grade 6 clarity without losing meaning
Shortened lengthy sentences to improve readability and flow
Converted a dense, difficult step into a clear, bulleted list of actionable tasks
Replaced overly technical words with simpler language
Clarified technical concepts to make them understandable for non-specialist readers
Shifted tone from passive to active voice to increase directness

Testing: I used the Hemmingway app to confirm readability and studied the terms individually to ensure they were all updated.

[ ✔️] I have read the contributing guidelines
[ ✔️] I have signed the F5 Contributor License Agreement (CLA)
[✔️] I have rebased my branch onto main
[✔️ ] I have ensured my PR is targeting the main branch and pulling from my branch from my own fork
[✔️ ] I have ensured that the commit messages adhere to Conventional Commits
[ ✔️] I have ensured that documentation content adheres to the style guide
[ ✔️] If the change involves potentially sensitive changes¹, I have assessed the possible impact
[ ✔️] If applicable, I have added tests that prove my fix is effective or that my feature works
[ ✔️] I have ensured that existing tests pass after adding my changes
[✔️ ] If applicable, I have updated README.md and CHANGELOG.md

Potentially sensitive changes include anything involving code, personally identify information (PII), live URLs or significant amounts of new or revised documentation. Please refer to our style guide for guidance about placeholder content. ↩

jawfu-M added 29 commits

May 7, 2025 16:39


          Update virtual-machines-for-nginx.md

81316e0


          Update virtual-machines-for-nginx.md

ebfa5b1


          Update virtual-machines-for-nginx.md

5d1394c


          Update virtual-machines-for-nginx.md

4c529b1


          Update virtual-machines-for-nginx.md

e8bbae5


          Update virtual-machines-for-nginx.md

07993b3


          Update virtual-machines-for-nginx.md

a768195


          Update virtual-machines-for-nginx.md

60562ec


          Update virtual-machines-for-nginx.md

08c045a


          Update virtual-machines-for-nginx.md

f838c97


          Merge branch 'nginx:main' into Update-docs-issue147

242c772


          Update virtual-machines-for-nginx.md

f0f4293


          Update virtual-machines-for-nginx.md

4c41fe3


          Update virtual-machines-for-nginx.md

3584dc9


          Update virtual-machines-for-nginx.md

d0e1565


          Update virtual-machines-for-nginx.md

c15634a


          Update virtual-machines-for-nginx.md

8583d13


          Update virtual-machines-for-nginx.md

e877562


          Update virtual-machines-for-nginx.md

04a193b


          Update virtual-machines-for-nginx.md

b6d5176


          Update virtual-machines-for-nginx.md

2d1750b


          Update virtual-machines-for-nginx.md

c46588e


          Update virtual-machines-for-nginx.md

539711c


          Update virtual-machines-for-nginx.md

78d62c9


          Update virtual-machines-for-nginx.md

338a7c0


          Update virtual-machines-for-nginx.md

f49fab3


          Update virtual-machines-for-nginx.md

728337c


          Update virtual-machines-for-nginx.md

feacb0b


          Update virtual-machines-for-nginx.md

1033dc4

jawfu-M requested a review from a team as a code owner

May 27, 2025 17:46

jawfu-M and others added 15 commits

July 3, 2025 23:47


          Update virtual-machines-for-nginx.md

27b88e7

Co-authored-by: Alan Dooley <[email protected]>


          Update virtual-machines-for-nginx.md

725514f

Co-authored-by: Alan Dooley <[email protected]>


          Update virtual-machines-for-nginx.md

62a6832

Co-authored-by: Alan Dooley <[email protected]>


          Update virtual-machines-for-nginx.md

86817d5

Co-authored-by: Alan Dooley <[email protected]>


          Update virtual-machines-for-nginx.md

0e3f654

Co-authored-by: Alan Dooley <[email protected]>


          Update virtual-machines-for-nginx.md

e830b62

Co-authored-by: Alan Dooley <[email protected]>


          Update virtual-machines-for-nginx.md

bb91bfc

Co-authored-by: Alan Dooley <[email protected]>


          Update virtual-machines-for-nginx.md

deca77b

Co-authored-by: Alan Dooley <[email protected]>


          Update virtual-machines-for-nginx.md

187071c

Co-authored-by: Alan Dooley <[email protected]>


          Update virtual-machines-for-nginx.md

f50d31b

Co-authored-by: Alan Dooley <[email protected]>


          Update virtual-machines-for-nginx.md

5f8398a

Co-authored-by: Alan Dooley <[email protected]>


          Update virtual-machines-for-nginx.md

d7b7aa6

Co-authored-by: Alan Dooley <[email protected]>


          Update virtual-machines-for-nginx.md

78a47d4

Co-authored-by: Alan Dooley <[email protected]>


          Update virtual-machines-for-nginx.md

22de585


          Update virtual-machines-for-nginx.md

3bf32cc

Author

jawfu-M commented Jul 4, 2025

Sort of LGTM: I made a large amount of suggestions to fix formatting issues introduced by the PR.

Most of them related to inline links being turned into production URLs and raw HTML being added to the Markdown text.

I'm happy to give an approval on the basis of my edit suggestions being implemented, but @y82 is the final call on if this can be merged or not.

Hi @ADubhlaoich 👋

Thank you for your thoughtful suggestions! I’ve committed all the changes and will closely review the rest of the file to catch any similar issues.

Really appreciate your patience as I get up to speed (Whew!). Your feedback has been incredibly helpful. Please let me know if you spot anything else.

Thank you so much once again. :)


          Merge branch 'main' into Update-docs-issue147

b58afba

JTorreG reviewed

View reviewed changes

content/nginx/deployment-guides/microsoft-azure/virtual-machines-for-nginx.md


		2. Click the Virtual machines icon. Or click the stacked lines icon (☰) in the top-left corner and select Virtual machines from the menu.

Contributor

JTorreG Jul 7, 2025 •

edited

Loading

Suggested change

      
            2. Click the Virtual machines icon. Or click the stacked lines icon (☰) in the top-left corner and select Virtual machines from the menu.
          
            2. Select the Virtual machines icon. Or select the stacked lines icon (☰) in the top-left corner and select Virtual machines from the menu.

https://github.com/nginx/documentation/blob/main/documentation/style-guide.md#:~:text=click%20vs%20select,Use%20%22select%22.

JTorreG reviewed

View reviewed changes

content/nginx/deployment-guides/microsoft-azure/virtual-machines-for-nginx.md

    
                 <img src="/nginx/images/azure-portal.png" alt="screenshot of top navigation bar at Microsoft Azure portal" width="1024" height="226" class="aligncenter size-full image-64310" style="border:2px solid #666666; padding:2px; margin:2px;" />

              3. On the **Virtual machines** page that opens, click **<span style="color:#4d9bdc;">+</span> Add** in the upper left corner.

              3. On the Virtual machines page that opens, click **+ Add** in the upper left corner.

Contributor

JTorreG Jul 7, 2025

Suggested change

      
            3. On the Virtual machines page that opens, click **+ Add** in the upper left corner.
          
            3. On the Virtual machines page that opens, select **+ Add** in the upper left corner.

JTorreG reviewed

View reviewed changes

content/nginx/deployment-guides/microsoft-azure/virtual-machines-for-nginx.md

+              When this guide was first published, the hourly cost for the six VMs was only $0.008. And this costlier than VMs with basic IP addresses. For current pricing, see the [Microsoft documentation](https://azure.microsoft.com/en-us/pricing/details/ip-addresses/).
+              Depending on your work load, you might need up to 6 VMs. Follow these steps:
+                - Open the **Networking** tab on the **Create a virtual machine** window.
+                - Click  _Create new_ below the **Public IP** field.

Contributor

JTorreG Jul 7, 2025

Suggested change

      
              - Click  _Create new_ below the **Public IP** field.
          
              - Select  _Create new_ below the **Public IP** field.

JTorreG reviewed

View reviewed changes

content/nginx/deployment-guides/microsoft-azure/virtual-machines-for-nginx.md

-                 <a href="/nginx/images/azure-create-vm-networking.png"><img src="/nginx/images/azure-create-vm-networking.png" alt="screenshot of 'Networking' tab on Azure 'Create a virtual machine' page" width="1024" height="718" class="aligncenter size-full wp-image-64994" style="border:2px solid #666666; padding:2px; margin:2px;" /></a>
+              When this guide was first published, the hourly cost for the six VMs was only $0.008. And this costlier than VMs with basic IP addresses. For current pricing, see the [Microsoft documentation](https://azure.microsoft.com/en-us/pricing/details/ip-addresses/).
+              Depending on your work load, you might need up to 6 VMs. Follow these steps:

Contributor

JTorreG Jul 7, 2025

Suggested change

      
            Depending on your work load, you might need up to 6 VMs. Follow these steps:
          
            Depending on your workload, you might need up to 6 VMs. Follow these steps:

JTorreG reviewed

View reviewed changes

content/nginx/deployment-guides/microsoft-azure/virtual-machines-for-nginx.md

+                - Click  _Create new_ below the **Public IP** field.
+                - In the **Create public IP address column** that opens, click the **Standard Radio button** under **SKU**.
+                - In the **Name** field, accept the default created by Azure, ngx-plus-1-ip.
+                - Click the _Ok_  button.

Contributor

JTorreG Jul 7, 2025

Suggested change

      
              - Click the _Ok_  button.
          
              - Select _Ok_.

When referring to a button by the label it is showing on screen there is no need to add "button" after. "Select Apply, Select Cancel, etc"

JTorreG reviewed

View reviewed changes

content/nginx/deployment-guides/microsoft-azure/virtual-machines-for-nginx.md


		<a href="/nginx/images/azure-create-vm-networking.png"><img src="/nginx/images/azure-create-vm-networking.png" alt="screenshot of 'Networking' tab on Azure 'Create a virtual machine' page" width="1024" height="718" class="aligncenter size-full wp-image-64994" style="border:2px solid #666666; padding:2px; margin:2px;" /></a>
		When this guide was first published, the hourly cost for the six VMs was only $0.008. And this costlier than VMs with basic IP addresses. For current pricing, see the [Microsoft documentation](https://azure.microsoft.com/en-us/pricing/details/ip-addresses/).

Contributor

JTorreG Jul 7, 2025

The first sentence does not make sense and needs to be rewritten.

JTorreG reviewed

View reviewed changes

content/nginx/deployment-guides/microsoft-azure/virtual-machines-for-nginx.md

    
                 If all of your settings are valid, a summary of them appears under the **Validation passed** banner, as in the following screenshot.

                 After you've completed your changes, click the _Review + create_ button at the bottom of the **Create a virtual machine** page.

Contributor

JTorreG Jul 7, 2025 •

edited

Loading

Suggested change

      
               After you've completed your changes, click the _Review + create_ button at the bottom of the **Create a virtual machine** page.
          
               After you've completed your changes, select _Review + create_ at the bottom of the **Create a virtual machine** page.

JTorreG reviewed

View reviewed changes

content/nginx/deployment-guides/microsoft-azure/virtual-machines-for-nginx.md

    
                 To change any settings, open the appropriate tab. If the settings are correct, click the <span style="background-color:#137ad1; color:white;"> Create </span> button.

                 You’ll find a summary of your setting under the **Validation passed** banner. Ensure they’re suitable. Then, click on <span style="background-color:#137ad1; color:white;"> Create </span>

Contributor

JTorreG Jul 7, 2025

Suggested change

      
               You’ll find a summary of your setting under the **Validation passed** banner. Ensure they’re suitable. Then, click on <span style="background-color:#137ad1; color:white;"> Create </span> 
          
               You’ll find a summary of your setting under the **Validation passed** banner. Ensure they’re suitable. Then, select Create.

While the original doc is using a span here, we are moving away from using raw HTML, so this is a good chance to correct that.

JTorreG reviewed

View reviewed changes

content/nginx/deployment-guides/microsoft-azure/virtual-machines-for-nginx.md

    
                 If you chose in [Step 4](#create-vm_Basics) to generate a new key pair, a {{<nb>}}**Generate new key pair**{{</nb>}} window pops up. Click the <span style="background-color:#137ad1; color:white; white-space: nowrap;"> Download key and create private resource </span> button.

                 If you generated a new key pair in [Step 4](#create-vm_Basics), a _Generate new key pair_ window pops up. Click on the _Download key and create private resource_ button.

Contributor

JTorreG Jul 7, 2025

Suggested change

      
               If you generated a new key pair in [Step 4](#create-vm_Basics), a _Generate new key pair_ window pops up. Click on the _Download key and create private resource_ button.
          
               If you generated a new key pair in [Step 4](#create-vm_Basics), a _Generate new key pair_ window pops up. Select _Download key and create private resource_.

JTorreG reviewed

View reviewed changes

content/nginx/deployment-guides/microsoft-azure/virtual-machines-for-nginx.md

    
                 <a href="/nginx/images/azure-create-vm-validation-passed.png"><img src="/nginx/images/azure-create-vm-validation-passed.png" alt="screenshot of validation message on Azure 'Create a virtual machine' page" width="1024" height="954" class="aligncenter size-full image-64993" style="border:2px solid #666666; padding:2px; margin:2px;" /></a>

                 It takes a few minutes for a VM to deploy. When it's ready, a summary of associated resources appears, as in the following screenshot.

                 VM deployment only takes a few minutes. After that, you’ll get a summary of your resources. Just like in the following screenshot.

Contributor

JTorreG Jul 7, 2025

Suggested change

      
               VM deployment only takes a few minutes. After that, you’ll get a summary of your resources. Just like in the following screenshot. 
          
                The VM deployment takes a few minutes. After that, you’ll get a summary of your resources. See an example in the following screenshot.

Avoid "just", "only" and similar expressions

JTorreG reviewed

View reviewed changes

content/nginx/deployment-guides/microsoft-azure/virtual-machines-for-nginx.md

    
            @@ -218,7 +226,7 @@ To streamline the process of installing NGINX Open Source on multiple VMs, you c
          
              ### Creating a VM from the Image

              It takes a few moments for the image to be created. When it's ready, you can create VMs from it with NGINX Open Source already installed.

              An Azure image takes only a few moments to deploy. When it’s ready, you can create VMs from it with NGINX Open Source already installed.

Contributor

JTorreG Jul 7, 2025

Suggested change

      
            An Azure image takes only a few moments to deploy. When it’s ready, you can create VMs from it with NGINX Open Source already installed.
          
            An Azure image takes a few moments to deploy. When it’s ready, you can create VMs from it with NGINX Open Source already installed.

See my previous comment

JTorreG reviewed

View reviewed changes

content/nginx/deployment-guides/microsoft-azure/virtual-machines-for-nginx.md

    
            @@ -228,7 +236,7 @@ It takes a few moments for the image to be created. When it's ready, you can cre
          
                 <a href="/nginx/images/azure-create-image-create-vm.png"><img src="/nginx/images/azure-create-image-create-vm.png" alt="screenshot of details page for Azure 'ngx-plus-1-image' image" width="1024" height="426" class="aligncenter size-full wp-image-64986" style="border:2px solid #666666; padding:2px; margin:2px;" /></a>

              The **Create a virtual machine** page that opens is the same as in Step 4 of Creating a Microsoft Azure Virtual Machine, except that some fields have hardcoded values derived from the image and the **Image** field has the name of the image instead of an operating system. Return to that [step](#create-vm_Basics) to complete the VM creation.

              The **Create a VM** page looks like Step 4 in Creating a Microsoft Azure Virtual Machine, but some fields are pre-filled from your image. The **Image** field now shows the image name instead of an OS. Go back to that [step](#create-vm_Basics) to finish creating your VM.

Contributor

JTorreG Jul 7, 2025

Suggested change

      
            The **Create a VM** page looks like Step 4 in Creating a Microsoft Azure Virtual Machine, but some fields are pre-filled from your image. The **Image** field now shows the image name instead of an OS. Go back to that [step](#create-vm_Basics) to finish creating your VM.
          
            The **Create a VM** page is similar to the Step 4 in Creating a Microsoft Azure Virtual Machine, but some fields are pre-filled from your image. The **Image** field now shows the image name instead of an OS. Go back to that [step](#create-vm_Basics) to finish creating your VM.

y82 reviewed

View reviewed changes

content/nginx/deployment-guides/microsoft-azure/virtual-machines-for-nginx.md

    
            @@ -71,32 +73,38 @@ In addition, to install NGINX software by following the linked instructions, you
          
                 <a href="/nginx/images/azure-create-vm-basics.png"><img src="/nginx/images/azure-create-vm-basics.png" alt="screenshot of 'Basics' tab on Azure 'Create a virtual machine' page" width="1024" height="1168" class="aligncenter size-full wp-image-64995" style="border:2px solid #666666; padding:2px; margin:2px;" /></a>

                 <span id="create-vm_Networking"></span>

              5. If you are creating VMs to use in [Active-Active HA for NGINX Plus on Microsoft Azure Using the Azure Standard Load Balancer]({{< ref "high-availability-standard-load-balancer.md" >}}), the two NGINX Plus VMs in that deployment must have public IP addresses with SKU type **Standard** instead of the default **Basic**.

              5. For [Active-Active HA for NGINX Plus on Microsoft Azure Using the Azure Standard Load Balancer]({{< ref "high-availability-standard-load-balancer.md" >}}):

Contributor

y82 Jul 7, 2025

The original text of step 5 is still more understandable for me (although I understand it's not perfect) so I'd rather use the original version, thanks

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

community documentation product/nginx-plus