feat: Rework Manifest installation cases

[ADubhlaoich]

Proposed changes

This commit reworks the manifest installation document to instead become
a folder, with each individual page within covering exactly one use
case. The new structure guides a user completely from end to end on the
process necessary for installing NGINX Gateway Fabric NGINX Open Source
or NGINX Plus without using multiple documents.

It also includes general improvements to specification discoverability,
allowing readers to more easily find what parts of the Gateway API
specification are supported and what to expect from future releases.

Checklist

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

• I read the Contributing guidelines
• My branch adheres to the Git conventions
• My content changes adhere to the F5 NGINX Documentation style guide
• If my changes involve potentially sensitive information¹, I have assessed the possible impact
• I have waited to ensure my changes pass tests, and addressed any discovered issues

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. ↩

[github-actions]

✅ Deploy Preview will be available once build job completes!

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

---

[ADubhlaoich]

Pushed my latest changes.

Running into issues testing the NGINX Plus deployment: there's no problems in the actual installation process, but the pod never becomes ready due to a crash loop.

The nature of the deployment makes me assume it could be related to the license for the pod.

[ADubhlaoich]

The Plus deployment case now works as expected: I'd been trying to create consistency with Gateway Fabric and Ingress Controller processes.

The latter installs everything (including secrets) to the default namespace, whereas NGINX Gateway Fabric confines it all to its own namespace.

[ADubhlaoich]

The document for installing experimental resources is finished.

The original scope of improvements is now complete, though there is some nuance in the Plus deployment I am unsure about and will investigate internally.

Opening the PR for review.

[sjberman]

The files you added to content/includes/ngf/installation/manifests/ are technically not specific to manifest installations, helm has the same steps.

[sjberman]

This is the issue now with splitting into multiple docs. All those prerequisites in the NGINX Plus manifest doc are still required here. It now needs to be duplicated across multiple docs. Feels like experimental could still live in the main manifest docs.

[ADubhlaoich]

This document is intended as instructional material: it is a reference, explaining and showing what URLs need to be substituted if the user intends to use experimental.

It is a supplement to the existing documentation, not a replacement.

[mjang]

All those prerequisites in the NGINX Plus manifest doc are still required here.

It's one reason why we have "includes", ref https://github.com/nginx/documentation/blob/main/documentation/include-files.md

One of the principles that we're trying to follow is to "minimize" the number of hops -- IOW, the number of times a user has to switch between docs.

[sjberman]

This doc would still need to be updated then to include those steps I mentioned, because if someone comes straight here and attempts to install that NGINX Plus manifest, it won't work.

[ADubhlaoich]

The structure is designed such that a user will not come straight here.

The first two options a user is confronted with when navigating the Manifest section are the OSS or Plus documents.

If they elect to go to the Experimental page, the intent of the document is explained as part of the overview/introduction:

I can rework the text to be more explicit with the warnings, but in context, we treat a "standard" OSS or Plus deployments as the majority of use cases, and therefore separate the optional, non-critical information from their instructions.

If there is data available to suggest a significant amount of users deploy edge versions, I will rework this document into two entirely new documents which effectively replicate the new OSS and Plus documents except for alternative URLs.

[sjberman]

Experimental up until this point has been a fairly common install method for our users (though the policies that exist in experimental are being promoted to standard, so that may shift things).

Don't we have an issue if users step through the initial doc for OSS/Plus, but then visit the Experimental doc and realize that they needed to perform those steps before installing? It's not like you install NGF and then enable experimental features, it's part of the installation process.

[sjberman]

cert manager has to be installed in a specific way to support Gateway API, which is what we previously included in our docs

[ADubhlaoich]

What makes the installation unique?

[sjberman]

This doc describes the extra flags needed to install cert manager to support Gateway API. There's probably extra stuff in the doc that may not be necessary.

[ADubhlaoich]

I will investigate that document to understand the context: it might simply be a note added to the pre-requisite.

Both use cases in this PR currently deploy successfully with the instructions as-is, so I'm trying to understand the nuance where something could break.

[sjberman]

Actually for this particular doc, cert-manager doesn't need Gateway API features enabled. For our other doc that uses cert-manager though, it does. I'm assuming when I wrote this, I figured we use those flags so a user doesn't have to reinstall cert-manager later when performing the other use case.

[ADubhlaoich]

Reading the cert-manager documentation has actually caused me some confusion:

Since cert-manager 1.15, the Gateway API support is no longer gated behind a feature flag, but you still need to enable the Gateway API support.

I'm trying to grok if the separate steps to "enable the Gateway API support" are necessary, and what they might be for Manifests, since the docs are completely prioritizing Helm.

If it turns out cert-manager just "works" now (Which it seemed to be from a deployment perspective - I haven't tried any of the nuance use cases), then we simply add a note to either use cert-manager 1.15+ or manually enable the API for earlier releases.

[sjberman]

This doc would be the true test to see if it "just works", since it actually uses the Gateway API features of cert-manager.

[ADubhlaoich]

@sjberman I have resolved a few bits of feedback and responded to everything else.

This is a pattern that is being applied to all onboarding documentation: a user can follow each document in full vertical sequence to deploy in less than 10 minutes.

The only nuance is if they want to install experimental, which is not presumed as a default use case - for which they have a separate document explaining and providing replacement URLs for installation steps.

Outside of the existing Manifest installation document, none of the other onboarding documentation has been changed yet as I opted to replicate steps in-place as a proof of concept: this same pattern has already been applied to NGINX Ingress Controller's Helm documentation:

https://docs.nginx.com/nginx-ingress-controller/install/helm/

My intent is to rewrite all onboarding documentation to reduce each page to covering exactly one use case, delineating between OSS and Plus.

Users have an idea of what kind of deployment they're going to use off the bat, so giving them extra optional dials on an individual document (Choosing between OSS and Plus and whether or not to use experimental) adds extra friction to each journey, and may also be a reason some people think NGINX Gateway Fabric cannot be used without a Plus license.

If there are technical nuances that need to be addressed that detail is incredibly important (Such as the note about cert-manager - I successfully deployed OSS and Plus with these procedures 5 times without issue), but otherwise I don't think we should be prioritizing maintainer time over user time or clarity.

If examples risk being outdated, we can periodically update them - the docs team is even working on procedures to schedule investigating and testing product documentation regularly, so that we can trust they are still accurate.

We should not avoid maintaining reference information like Technical specifications on the basis that they might become outdated or will have to be updated with each release, because that information is critically important for end users.

[sjberman]

@ADubhlaoich I agree the value of including the Tech specs, and also don't want to avoid including them. However, saying that they "might get outdated" is optimistic. They will get outdated. We have problems updating it in our own repo where those dependency updates actually happen. It's a manual chore that I wish we could automate in our own README because we often forget to do it.

We can leave it in and update our release process doc to mention updating this at release time, which might be the best option for us. But in between that cadence, it will probably lag behind.