Add JWT license information to NGINX App Protect WAF documentation

[ADubhlaoich]

Overview

As a NGINX App Protect WAF user, I want information on adding my license file, So I can run NGINX App Protect WAF.

Description

This originally came in as a report from @aknot242 :

The App Protect WAF docs have not been updated to include the JWT license requirement. Examples: the installation page has package installation instructions, as well as Docker image creation/deployment steps. None of these include the procedure to present the license JWT to the nginx instance, so it will fail to start.

It's a common use case that has largely been "solved" for most of the NGINX product installation documentation. As a result, I think all of the information needed for this likely already exists in include files.

When I shared this perspective, @travisamartin offered some advice:

Sounds like a plan -- Thank you!
Here are related includes that are used in the NGINX Plus installation guide and "About subscription licenses" doc: https://github.com/nginx/documentation/tree/main/content/includes/licensing-and-reporting

Steps

• Identify the include files which contain the relevant text fragments instructing the user on JWT requirements
• Review the rest of the documentation related to installation to ensure there is contextual consistency
• Add the include files to the relevant parts of NGINX App Protect WAF documentation

Acceptance criteria

• The user knows where to get their license token for NGINX Plus
• The user knows where to put the license token after obtaining it
• The user knows any additional steps necessary for the license token to be active

[ADubhlaoich]

There's two include files with nearly identical information:

https://github.com/nginx/documentation/blob/main/content/includes/licensing-and-reporting/download-jwt-crt-from-myf5.md
https://github.com/nginx/documentation/blob/main/content/includes/licensing-and-reporting/download-jwt-from-myf5.md

The former is a bit more verbose, so I'm inclined to go with that - though I'm going to check NIM and N1C for what the most recent conventions are.

The secondary step seems to be this text fragment:

https://github.com/nginx/documentation/blob/main/content/includes/licensing-and-reporting/apply-jwt.md

I think the quickest fix for this issue prior to rewriting each page will be to add this as a post-installation section to NGINX Plus set-up where relevant.

[ADubhlaoich]

On farther investigation, it looks like the first file is used commonly in NGINX Plus documentation, while the second file is more common in NGINX Instance Manager documentation. In the latter case, it's actually part of nested include files to create a more complex set of instructions.

I'm not sure why both of these includes exist - I'm going to create a time box of two days for a consensus which to go with. It's outside the scope of this discrete issue, but we should consolidate them into one include for consistency.

[ADubhlaoich]

In an effort to reduce duplication of use cases, albeit requiring an extra hop, I think it would be best to explicitly direct users to the NGINX Plus documentation during set-up. NGINX Plus has a pattern of "heading for each operating system" while NGINX App Protect WAF has a pattern of "tab for each operating system".

I find both awkward for different reasons, but I think headings are the lesser evil to tabs.

Most of the NGINX Plus documentation coherently encapsulates the earliest steps of the NGINX Plus set-up steps for NGINX App Protect WAF: the only "extra" step is usually to add the NAP repository and install the package.

Duplicate effort for maintenance: if I were to push through with trying to scope each product purely to their own instructions, I'd axe most of the NAP content:

1. Collapse each set of duplicate instructions in NAP to their operating systems, either as tabs or headings
2. Direct the user to the NGINX Plus documentation for set-up of NGINX Plus as a prerequisite
3. Give them the "additional" NAP step afterwards

It reduces the maintenance overhead on NAP, ensures the instructions remain updated by making sure there is only one copy. Since NGINX Plus is upstream for all commercial NGINX products, its documentation also tends to be updated the earliest.

[travisamartin]

If possible, I’d recommend avoiding tabs—they add complexity to UX (especially on mobile) and increase content maintenance overhead. The syntax for tabs can also be a barrier for users unfamiliar with them.

I’ve observed in user testing that NAP users struggle with completing tasks due to frequent hops between documentation. If directing users to NGINX Plus docs helps streamline this, it could work, but I’d like to test whether it actually reduces friction or introduces new navigation challenges.

Would you be open to using headings instead of tabs while ensuring that any necessary NGINX Plus setup steps are summarized in-line before linking out? This might help users follow along without jumping back and forth too much.

[ADubhlaoich]

I'm absolutely all for removing the tabs - I plan to as part of the refactor effort. Since this is critical information I thought I would try to action it immediately, but investigating it has revealed larger scope issues around the way the installation documentation is structured.

A swap to headings would make it similar in structure to the NGINX Plus documentation: if users are being redirected to another documentation set, then having them look similar should in theory create less cognitive dissonance.

Of course, if the headings and structure match - maybe that's a case where includes can be used to cleanly replicate the critical information. Then the user doesn't need to hop, and we can ensure the instructions remain correct through only having to maintain the text fragments of the include.

[ADubhlaoich]

As a temporary fix, I have used the above includes to add a section just before the operating system tabs to give the user the context around downloading the license file.

I think it technically fulfills the acceptance criteria for this issue, but I am contending that this is a compromise until we have had more time to restructure the NAP documentation.

[ADubhlaoich]

Ticking off the last bit of acceptance criteria:

The user knows any additional steps necessary for the license token to be active

That's a "commercial-subscription-sales-engineering" level of concern and not something product documentation contends with.

I'm closing this issue, and associating it with the imminent NAP release.