Skip to content
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

Edited doc to improve readability #334

Merged
merged 5 commits into from
Mar 31, 2025

Conversation

noxian-byte
Copy link
Contributor

Proposed changes

Problem: The page had not been revised since May 2024.

Solution:

  • None of the screenshots contain Personally Identifying Information (PII)
  • The screenshots only contain information that is needed to follow the documentation
  • The only screenshot that may need an update is the UI that is in section 'Enabling Live Activity Monitoring'
  • Edits have been made to improve readability of the text

Please focus on (optional): I used the Hemingway Editor as instructed and have noticed that most of the sentences were marked as hard to read simply because of the length.How much emphasis is placed on reducing word count when readability is a priority?

This PR addresses Issue #138

@noxian-byte noxian-byte requested a review from a team as a code owner March 29, 2025 01:31
@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 Mar 29, 2025
@ADubhlaoich
Copy link
Contributor

How much emphasis is placed on reducing word count when readability is a priority?

If you can find ways to shorten sentences, I generally advocate for it. Longer sentences aren't necessarily better ones.

Copy link
Contributor

@ADubhlaoich ADubhlaoich left a comment

Choose a reason for hiding this comment

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

Generally LGTM!

Making sure @y82 is tagged as the assigned TW (technical writer) for NGINX Plus: I'm going to flag the use of links internally.

We want all our links handled using Hugo references, and have a directive to avoid any inline HTML.

@mjang
Copy link
Contributor

mjang commented Mar 31, 2025

How much emphasis is placed on reducing word count when readability is a priority?

If you can find ways to shorten sentences, I generally advocate for it. Longer sentences aren't necessarily better ones.

Readability calculators such as Flesch-Kincaid credit shorter sentences and words with fewer syllables. Here's their equation:

(0.39 * (words / sentences)) + (11.8 * (syllables / words)) - 15.59

Copy link
Contributor

@mjang mjang left a comment

Choose a reason for hiding this comment

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

Note: I've corrected the entry which refers to Nginx. We use NGINX in our documentation.

@mjang
Copy link
Contributor

mjang commented Mar 31, 2025

@noxian-byte thank you for your contribution!

@mjang mjang merged commit 1a7e357 into nginx:main Mar 31, 2025
6 checks passed
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.

4 participants