Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

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.

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

Already on GitHub?Sign in to your account

Open
jawfu-M wants to merge63 commits intonginx:main
base:main
Choose a base branch
Loading
fromjawfu-M:Update-docs-issue147

Conversation

jawfu-M
Copy link

@jawfu-Mjawfu-M commentedMay 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 thecontributing guidelines
  • [ ✔️] I have signed theF5 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 toConventional Commits
  • [ ✔️] I have ensured that documentation content adheres tothe style guide
  • [ ✔️] If the change involves potentially sensitive changes1, 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 updatedREADME.md andCHANGELOG.md

Footnotes

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

jawfu-M added29 commitsMay 7, 2025 16:39
@jawfu-Mjawfu-M requested a review froma team as acode ownerMay 27, 2025 17:46
jawfu-Mand others added14 commitsJuly 4, 2025 00:43
Co-authored-by: Alan Dooley <github@adubhlaoi.ch>
Co-authored-by: Alan Dooley <github@adubhlaoi.ch>
Co-authored-by: Alan Dooley <github@adubhlaoi.ch>
Co-authored-by: Alan Dooley <github@adubhlaoi.ch>
Co-authored-by: Alan Dooley <github@adubhlaoi.ch>
Co-authored-by: Alan Dooley <github@adubhlaoi.ch>
Co-authored-by: Alan Dooley <github@adubhlaoi.ch>
Co-authored-by: Alan Dooley <github@adubhlaoi.ch>
Co-authored-by: Alan Dooley <github@adubhlaoi.ch>
Co-authored-by: Alan Dooley <github@adubhlaoi.ch>
Co-authored-by: Alan Dooley <github@adubhlaoi.ch>
Co-authored-by: Alan Dooley <github@adubhlaoi.ch>
@jawfu-M
Copy link
Author

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. :)


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

@JTorreGJTorreGJul 7, 2025•
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Suggested change
2.Click the Virtual machines icon. Orclick the stacked lines icon (☰) in the top-left corner and select Virtual machines from the menu.
2.Select the Virtual machines icon. Orselect 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.

<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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

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.

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Suggested change
-Click_Create new_ below the**Public IP** field.
-Select_Create new_ below the**Public IP** field.


<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:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Suggested change
Depending on yourwork load, you might need up to 6 VMs. Follow these steps:
Depending on yourworkload, you might need up to 6 VMs. Follow these steps:

- 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

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"


<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/).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

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


If all of yoursettings are valid, a summary of them appears underthe **Validation passed**banner, as in the following screenshot.
After you've completed yourchanges, click the _Review + create_ button at the bottom ofthe **Create a virtual machine**page.
Copy link
Contributor

@JTorreGJTorreGJul 7, 2025•
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

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.


To change any settings, opentheappropriate tab. If the settings are correct, clickthe <span style="background-color:#137ad1; color:white;"> Create </span>button.
You’ll find a summary of your setting underthe**Validation passed** banner. Ensure they’re suitable. Then, clickon <span style="background-color:#137ad1; color:white;"> Create </span>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Suggested change
You’ll find a summary of your setting under the**Validation passed** banner. Ensure they’re suitable. Then,click on <spanstyle="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.


If youchosein [Step 4](#create-vm_Basics) to generate a new key pair, a{{<nb>}}**Generate new keypair**{{</nb>}} window pops up. Click the<span style="background-color:#137ad1; color:white; white-space: nowrap;"> Downloadkey and create privateresource </span> button.
If yougenerated a new key pairin [Step 4](#create-vm_Basics), a_Generate new keypair_ window pops up. Clickonthe_Downloadkey and create privateresource_ button.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

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_.


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

Ittakes a few minutes for a VM to deploy. When it's ready,a summary ofassociated resources appears, as in the following screenshot.
VM deployment onlytakes a few minutes. After that, you’ll geta summary ofyour resources. Just like in the following screenshot.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Suggested change
VM deploymentonlytakes a few minutes. After that, you’ll get a summary of your resources.Just like in the following screenshot.
TheVM 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

@@ -218,7 +226,7 @@ To streamline the process of installing NGINX Open Source on multiple VMs, you c

### Creating a VM from the Image

Ittakes a few momentsfor the imagetobe created. When it's ready, you can create VMs from it with NGINX Open Source already installed.
An Azure imagetakesonlya few moments todeploy. When it’s ready, you can create VMs from it with NGINX Open Source already installed.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Suggested change
An Azure image takesonlya 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

@@ -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 avirtual machine** pagethat opens is the same asinStep 4 ofCreating a Microsoft Azure Virtual Machine,except thatsome fieldshave hardcoded values derivedfromthe image and the**Image** fieldhas the name ofthe image instead of anoperating system. Returnto that [step](#create-vm_Basics) tocomplete the VM creation.
The **Create aVM** pagelooks like Step 4in Creating a Microsoft Azure Virtual Machine,butsome fieldsare pre-filledfromyour image. The**Image** fieldnow showsthe imagenameinstead of anOS. Go backto that [step](#create-vm_Basics) tofinish creating your VM.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Suggested change
The**Create a VM** pagelooks 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** pageis 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.

@@ -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" >}}):
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

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 freeto join this conversation on GitHub. Already have an account?Sign in to comment
Reviewers

@y82y82y82 requested changes

@JTorreGJTorreGJTorreG left review comments

@ADubhlaoichADubhlaoichADubhlaoich approved these changes

Requested changes must be addressed to merge this pull request.

Assignees

@jawfu-Mjawfu-M

Labels
communitydocumentationImprovements or additions to documentationproduct/nginx-plusNGINX Plus (and NGINX Open Source in docs.ngninx.com)
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

5 participants
@jawfu-M@mjang@ADubhlaoich@y82@JTorreG
[8]ページ先頭
©2009-2025 Movatter.jp