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 going to continually change as Gateway API adds new CRDs. Doesn't seem maintainable.

[ADubhlaoich]

Unless the new CRDs are being added daily, I don't know why there wouldn't be a problem updating the example output periodically.

They're meant to give an impression of output, and are hidden by default.

[sjberman]

I don't know why there wouldn't be a problem updating the example output periodically

When adding a new CRD, nobody is going to remember that they are referenced in some text output in a random doc. It'll only be when someone is looking at the docs at some point and realizes the inconsistency. It's not the end of the world to be innacurate, but inevitably someone is going to get confused why their output doesn't match what's here.

[sjberman]

This is going to continually change as we add new CRDs. Doesn't seem maintainable.

[ADubhlaoich]

Unless the new CRDs are being added daily, I don't know why there wouldn't be a problem updating the example output periodically.

They're meant to give an impression of output, and are hidden by default.

[sjberman]

This is going to continually change as Gateway API adds new CRDs. Doesn't seem maintainable.

[ADubhlaoich]

Unless the new CRDs are being added daily, I don't know why there wouldn't be a problem updating the example output periodically.

They're meant to give an impression of output, and are hidden by default.

[sjberman]

I really want there to be a better way to do this. We are updating this table very frequently (it's already out of date here). Keeping this in sync is going to be forgotten, because we already forget to do it sometimes in our own repo.

[ADubhlaoich]

Technical specifications are a standard deliverable for every product.

I don't think hiding this information from users is an acceptable choice to avoid the possibility it may occasionally be outdated.

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

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

[sjberman]

Same comment, will be out of date.

[ADubhlaoich]

Unless the new CRDs are being added daily, I don't know why there wouldn't be a problem updating the example output periodically.

They're meant to give an impression of output, and are hidden by default.

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