Skip to content

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 our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 30 commits into
base: main
Choose a base branch
from

Conversation

jawfu-M
Copy link

@jawfu-M jawfu-M commented May 27, 2025

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 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 updated README.md and CHANGELOG.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 to our style guide for guidance about placeholder content.

@jawfu-M jawfu-M requested a review from a team as a code owner May 27, 2025 17:46
@github-actions github-actions bot added documentation Improvements or additions to documentation product/nginx-plus NGINX Plus (and NGINX Open Source in docs.ngninx.com) labels May 27, 2025
Copy link

github-actions bot commented May 27, 2025

✅ All required contributors have signed the F5 CLA for this PR. Thank you!
Posted by the CLA Assistant Lite bot.

@jawfu-M
Copy link
Author

jawfu-M commented May 27, 2025

I have hereby read the F5 CLA and agree to its terms

@mjang
Copy link
Contributor

mjang commented May 27, 2025

@jawfu-M thanks so much for your proposed contribution!

@mjang mjang changed the title Update docs issue147 Proposed rewrite to "Creating Microsoft Azure Virtual Machines for NGINX Open Source and F5 NGINX Plus" May 27, 2025
@mjang
Copy link
Contributor

mjang commented May 27, 2025

"for the record" offered support / encouragement via DM in Write the Docs slack

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
community documentation Improvements or additions to documentation product/nginx-plus NGINX Plus (and NGINX Open Source in docs.ngninx.com)
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants