Analyze NGINX Plus Deployment Guide: Using NGINX/NGINX Plus as the Ingress Controller

[mjang]

This page, https://docs.nginx.com/nginx/deployment-guides/amazon-web-services/ingress-controller-elastic-kubernetes-services/ has not been revised since March 2020.

You can review and edit the source code for the page directly in our repository. You can edit it directly, as described in Editing files.

Alternatively, If you know Git, you're welcome to fork the repository and use your skills to set up a Pull request.

We need to audit this page.

Here's what we'd like you to do (tasks):

• Audit screenshots

  • Update if they're out of date
  • Evaluate the screenshots:
    • Do they include too much info, such as Personally Identifying Information
    • Do we need all the information in the screenshot
    • Do we even need the screenshot, since it's from "someone else's" UI

• Evaluate the page for readability

  • Use the process described in Good first issues for writers -- focused on readability #72
  • Update the content of the page

If you're not (yet) comfortable with Git, you're welcome to post your answers to this issue in a Discussion.

• We'll be happy to give you credit!

If you haven't been able to do everything in this issue, that's OK. We appreciate all the help that we can get.

[madebydna]

✋ I would like to work on this one. (Duplicate of #97)

[mjang]

@madebydna The issue is yours. Good luck, and you're welcome to ping me with questions!

[madebydna]

@mjang, I started working on the document and have a few questions:

1. In addition to improving readability, fixing links, etc. is it allowed to (slightly) change the content by adding some sentences to clarify things, or to give additional hints?
   • One example would be to note that setting up the EKS cluster using eksctl can take several minutes (it took about 10 minutes for me, which of course can vary)
   • Another example would be to explicitly note that "Pushing the NGINX Plus Ingress Controller Image to AWS ECR" is only required if you're either using the enterprise version of the product or a custom-built open source image. This is arguably clear from the title but since we're describing the usage of two different products, it might not hurt to make things explicit.
2. I'm currently at the step of Installing the NGINX Plus Ingress Controller which links to another page in the documentation. There are two ways of installing the Ingress Controller - one via manifests, and the other with a Helm chart. The current doc links to the installation instructions via manifests and I was wondering if we should link to the Helm installation instead. Helm-based installation is usually a bit shorter/simpler (i.e. one command helm install ... vs. installing multiple manifests individually) but I suppose it requires additional dependencies. What are your thoughts on this?
3. For steps that need to be done for both the enterprise and open source product, would it be okay to just say "NGINX Ingress Controller," or otherwise indicate that we mean both products? An example would be the step of "Installing the NGINX Plus Ingress Controller."

[mjang]

@madebydna I love your approach in your point 1.

• You're welcome to add content to clarify
  • "several minutes" sounds like an excellent addition. (I know when a command takes a long time to respond, I worry)
  • I appreciate the push to clarify conditions for "Pushing the NGINX Plus Ingress Controller"

I need to ask around w/r/t your other questions

[jputrino]

Pinging @shaun-nx for guidance on the question about how we refer to NGINX Ingress Controller for open source vs Plus use cases.

[madebydna]

@mjang and @jputrino, I actually just noticed that there is a note near the top of the document stating:

The instructions in this document apply to both the NGINX and NGINX Plus Ingress Controllers for Kubernetes. For ease of reading, the document refers to NGINX Plus only.

This means that "NGINX Plus" used in titles usually references both products. Sorry about the confusion! I'll be sure to check, though, if a particular step only applies to one of the products, and make a note if it does.

[madebydna]

@mjang now that I've gotten further in following the instructions, I realized that the steps after "Installing the NGINX Plus Ingress Controller" require editing some manifest files, so following the Installation with Manifests page is correct, so never mind my second question from this morning. 🙂

[mjang]

@madebydna Thanks for your questions, your persistence, and your patience! Let us know if you have more questions (or if we missed anything.