Skip to content

Conversation

@dkleinF5
Copy link
Contributor

@dkleinF5 dkleinF5 commented Nov 25, 2025

Proposed changes

Checklist

Before sharing this pull request, I completed the following checklist:

Footnotes

  1. Potentially sensitive information includes personally identify information (PII), authentication credentials, and live URLs. Refer to the style guide for guidance about placeholder content.

@dkleinF5 dkleinF5 requested a review from a team as a code owner November 25, 2025 14:32
@github-actions github-actions bot added documentation Improvements or additions to documentation product/waf Issues related to F5 WAF for NGINX labels Nov 25, 2025
@github-actions
Copy link

github-actions bot commented Nov 25, 2025

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

@github-actions
Copy link

Deploy Preview will be available once build job completes!

Name Link
😎 Deploy Preview https://frontdoor-test-docs.nginx.com/previews/docs/1485/

@dkleinF5 dkleinF5 changed the title docs: add missing prerequisite for installation [Draft] docs: add missing prerequisite for installation Nov 25, 2025
@dkleinF5 dkleinF5 requested a review from a team as a code owner November 26, 2025 08:08
@dkleinF5
Copy link
Contributor Author

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

@dkleinF5 dkleinF5 force-pushed the waf/missing-prerequisite branch from d366350 to dc87dc4 Compare November 27, 2025 07:11
@ADubhlaoich ADubhlaoich self-requested a review November 27, 2025 11:11
@ADubhlaoich ADubhlaoich changed the base branch from main to waf-release-5.10 November 28, 2025 16:57
@ADubhlaoich ADubhlaoich changed the base branch from waf-release-5.10 to main December 1, 2025 10:09
@dkleinF5 dkleinF5 force-pushed the waf/missing-prerequisite branch from c0adb94 to d54baa0 Compare December 1, 2025 12:34
@dkleinF5 dkleinF5 changed the title [Draft] docs: add missing prerequisite for installation Docs: add missing prerequisite for installation Dec 1, 2025
@dkleinF5 dkleinF5 force-pushed the waf/missing-prerequisite branch from d54baa0 to 9f5a581 Compare December 1, 2025 17:13
Copy link
Contributor

@JTorreG JTorreG left a comment

Choose a reason for hiding this comment

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

There is a TODO label

@dkleinF5 dkleinF5 force-pushed the waf/missing-prerequisite branch from dfc4c24 to 04698aa Compare December 2, 2025 07:57
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: approval pending feedback.

Please run the linting tools on this branch, which can be executed automatically with pre-commit.

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.

Some more minor changes for content flow and formatting.

@dkleinF5 dkleinF5 force-pushed the waf/missing-prerequisite branch 2 times, most recently from 5645ca7 to 23eddc1 Compare December 3, 2025 15:34
@dkleinF5 dkleinF5 requested a review from ADubhlaoich December 3, 2025 15:34
@dkleinF5 dkleinF5 force-pushed the waf/missing-prerequisite branch from ea72132 to cc0a686 Compare December 15, 2025 09:17
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.

I have already given this feedback and it has not been addressed: there has been unnecessary detail added to every single set of pre-requisites.

These are not pre-requisites: they are instructions, and they are redundant instructions.

Immediately after the user finishes reading the "Before you begin" section, they are explicitly guided through the steps involved in downloading and configuring the credentials needed to follow the rest of the document.

Comment on lines 34 to 44
{{< call-out "note" >}}
If you are using NGINX Open Source for your Multi-container or Hybrid configuration, you do not need the JWT license file.
{{< /call-out >}}

{{< include "licensing-and-reporting/download-jwt-ssl-key-from-myf5.md" >}}

{{< call-out "important" >}}
The provided Dockerfile for NGINX Plus automatically handles placing the JWT license file in `/etc/nginx/` during image build. If you use a custom Dockerfile, you must ensure the JWT license is copied to this location.
{{< /call-out >}}

{{< call-out "note" >}} Starting from [NGINX Plus Release 33]({{< ref "nginx/releases.md#r33" >}}), a JWT file is required for each NGINX Plus instance. For more information, see [About Subscription Licenses]({{< ref "/solutions/about-subscription-licenses.md">}}). {{< /call-out >}}
Copy link
Member

Choose a reason for hiding this comment

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

This is an excessive use of consecutive call-outs.

Call-outs are intended to draw the user's attention to something highly specific they need to take extra care of: if you over-use them, everything looks important, and nothing looks important as a result.

  1. The content of the first can be replaced with an anchor link to "skip" the unnecessary section for OSS users
  2. The second call-out is fine, and a good example of how call-outs should primarily be used
  3. The third call-out is redundant, because the instructions involving NGINX Plus guide the user towards using a JWT file: there's no point telling someone they will need to do something if you're already expecting them to do it as part of the instructions

@dkleinF5
Copy link
Contributor Author

I have already given this feedback and it has not been addressed: there has been unnecessary detail added to every single set of pre-requisites.

These are not pre-requisites: they are instructions, and they are redundant instructions.

Immediately after the user finishes reading the "Before you begin" section, they are explicitly guided through the steps involved in downloading and configuring the credentials needed to follow the rest of the document.

@ADubhlaoich Are you able to speak with Aviv Dahan about this. This is something product requested.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation product/waf Issues related to F5 WAF for NGINX

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants