Good first issues for writers -- focused on readability

[mjang]

Is your feature request related to a problem? Please describe:

This "Epic" (group of issues) includes documents where we'd appreciate help with readability. We'd love to see improvements. One straightforward way to measure such improvements is with the Hemingway Editor, available from https://hemingwayapp.com/.

If you'd like to try to work one of these issues, make a note in the comments, or add your request to our discussions. We'll be happy to help you get started.

You're welcome to use a similar process on the documentation page of your choice! Just let us know in discussions, or if you know how, by creating an issue.

The improvement process

If you want to suggest improvements, we ask you to follow this process. (We're flexible. You're welcome to use similar tools.)

1. Take a page from docs.nginx.com. Copy the contents of that page to https://hemingwayapp.com/.
   • Tip: in Chrome, right-click on the page, and select "Open in Reading Mode". This selects "just" the text. so you don't have to worry about code in the documentation
   • Copy/paste the contents of the "Reading Mode" window. Paste it into https://hemingwayapp.com/.
2. In the upper-right, you'll see a "Readability" grade - This grade corresponds to a reading level associated with the document you copied
   • Ernest Hemingway is known for the readability of his work. Some of his best novel had a readability level of Us grade 4.
   • It's a challenge to craft "readable" technical documentation
3. We would like to see at least a two-grade level improvement in readability
   • Find a document that's at a grade level 9 or higher.
   • It's rare to find technical documents that are at or below grade level 7.
   • The Hemingway app is helpful. It lists sentences which are:
     • Hard to read
     • Very hard to read
   • Focus your work on these sentences
4. When you're done, submit your work. Show the grade level of the current document, along with your proposed change to improve readability.

If you know tools like Git, that's fantastic! You're welcome to submit pull requests to this repository, https://github.com/nginx/documentation. Unless you're an employee of F5/NGINX, you'll need to "fork" this reposotory. (If you don't know what that means, that's OK! You're even welcome to attach a Word document with your proposed changes!)

You can create your own readability issue

We've set this up based on the NGINX Plus Deployment Guides. Many of these guides have not been reviewed in years. I've created issues for the first of those guides.

If you find a guide not covered by available issues, you're welcome to create your own. In the upper right, you may see a "New Issue" button. You can use one of our templates, or set up a blank issue where you can copy/paste content from an existing issue.

Especially if you're a community contributor, be sure to tag us on the issue you create, @nginx/nginx-docs , or me, @mjang .

[mjang]

Notes from @travisamartin . I'll create some issues from these notes. I'll update and revise these notes for clarity

Install or Upgrade Security monitoring

• Want to use a mgmt plane
• Need to get it installed
• how to inst, N+, NIM, security monitoring

Desired output: feedback on what needs to be done with the doc

"Accessing the Web Interface"

• How to train contributors on how to work with includes
• Hugo is popular, so someone should have dealt with this issue before

"Installing N+" already mostly includes

• How would a contributor handle it

N+ Deployment Guides

• Are the screenshots up to date
• Can we remove some of them
• What would you change

NIM catalogs