NGINX App Protect WAF Refactor

[ADubhlaoich]

Description

This issue is an index of all of the context involved with refactoring the NGINX App Protect WAF documentation.

It was originally proposed as an effort for improving the overall user experience of using NGINX App Protect WAF documentation, but has since refined to include upcoming product rebranding as convergent priorities.

To get an impression of what the refactor will look like from a high-level information architecture perspective, you can navigate through this proof of concept.

Goals

The primary goal of this refactor is to make the documentation clear, communicative and useful.

The navigation experience should be intuitive, and match other parts of the NGINX portfolio. It allows for user familiarity with other products to inform how they navigate documentation.

A user should be able to easily identify what documentation is relevant to them based on their use case, which is affected by variables such as the form factor they choose to deploy NGINX App Protect, and which version.

Please see issues attached to this epic for atomic goals, stories and acceptance criteria.

User stories

As a NGINX App Protect WAF user,
I want information to be clear and easy to understand,
So I can easily deploy and configure my instances.

As a support engineer,
I want complete and accurate information,
So I can easily help users if they reach an inoperable state.

As a contributor,
I want the structure to be simplified,
So I can easily modify documentation.

Tasks

• Create a new sitemap for the overall documentation structure
• Add new concept and reference pages to fill gaps in existing content
• Migrate and update content from the existing documentation set
• Migrate and update content from NGINX Ingress Controller
• Break multi-purpose monolith pages into small, scoped use cases

[ADubhlaoich]

The deployment preview for the proof of concept was manually triggered from the waf/refactor branch.

The same branch will be used for the actual refactor work: a draft pull request will be created for previewing the ongoing progress.

Each individual issue with have a sub-branch from the refactor so that the scope of changes for review from stakeholders can be kept small, reducing noise.

[ADubhlaoich]

Four issues in: the work defined so far are largely gap-fillers for content the product does not have.

Many of the incoming issues will all explain what breaking up the monolithic documents will look like.

In practice it will likely take the most amount of time, since it will be rewriting tons of content to be adherent with general NGINX formatting and style.

Thankfully we have standardized how we present and structure many kinds of instructions, so once the issues are in place it's just a case of putting my head down and iterating on the work.

Pending some internal decision logs for timelines, but I was advised by an engineer that the end goal will likely be a September date for the WAF release with the new branding.