Skip to content

Conversation

ghost
Copy link

@ghost ghost commented Mar 29, 2025

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

@ghost ghost self-requested a review as a code owner March 29, 2025 01:31
@github-actions github-actions bot added documentation Improvements or additions to documentation product/nginx-plus Issues related to NGINX Plus (and NGINX Open Source in docs.nginx.com) labels Mar 29, 2025
@ADubhlaoich
Copy link
Member

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
Member

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

@ADubhlaoich ADubhlaoich requested a review from y82 March 31, 2025 09:22
@ADubhlaoich ADubhlaoich added the community Issues or pull requests started by community members label Mar 31, 2025
@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

@mjang mjang assigned ghost Mar 31, 2025
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 Issues or pull requests started by community members documentation Improvements or additions to documentation product/nginx-plus Issues related to NGINX Plus (and NGINX Open Source in docs.nginx.com)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants