User-oriented Architecture Guide

[mpstefan]

As a user or potential user of NGF
I want an architecture document that gives me a high level overview of NGF's architecture
So that I can understand how to operate and deploy NGF in my environment.

Acceptance

• The current architecture documentation page is reworked to focus solely on the usage and operation of NGF for users.
• All information that is only relevant for contributors is relegated to another developer-oriented architecture guide.
• The current traffic and configuration diagram should be split into two diagrams depicted two processes labeled with numbers:
  • A diagram depicting how a configuration change propagates through NGF.
  • A diagram depicting how traffic flows through NGF is ingested by the application hosted in Kubernetes
• Each diagram depicting a sequential process should describe each step in a table format (example)
• References to logging in any diagram are removed.
• A link to the contributor architecture documentation is present in a prominent location.

[mpstefan]

@ADubhlaoich Would you be able to take a look at our current architecture doc and give us some feedback on how effective it is at conveying our architecture as a potential user/cluster operator?

https://docs.nginx.com/nginx-gateway-fabric/overview/gateway-architecture/

[ADubhlaoich]

Reviewing the document, there's lots of ways to simplify the text as there's some redundancy and complex language.

There's also marketing-adjacent ambiguity in the initial paragraphs on what seems to be intended as technical reference:

NGINX Gateway Fabric separates the control plane and data plane into distinct deployments. This architectural separation enhances scalability, security, and operational isolation between the two components.

There's detail under the "Deployment Model and Architectural Overview" which explain what this actually means: it's an example of burying the lede.

It's been discussed already, but the implementation details of NGF may not be of interest to core "users": it's mostly of interest to possible contributors, so information in the "Component Communication Workflow" could be split into its own page and combined with some of the developer docs.

Although there's two listed audience members at the top of the document, it reads as though its trying to accomplish three things:

1. Introduce what NGINX Gateway Fabric is
2. Explain how to use NGINX Gateway Fabric from a system design perspective
3. Explain how NGINX Gateway Fabric is implemented

In contrast, here's similar documentation for NGINX Ingress Controller:

• About, which describes what NIC is
• The design of NGINX Ingress Controller, which gets into the implementation details like the current Architecture guide

The challenge is in overall content design: figuring out what to present to the reader when, and what the distinct purpose of one page actually is. If NGF requires some "advertising", the elevator pitch should probably be on another page, or part of overall design starting from the landing page, per #3252.

I'm a little bit buried under some work for NAP-WAF at the moment, but I can start work on the landing page this week to see if it addresses some of the identity problems this page is suffering from.

[sjberman]

I think "how it works" isn't just a contributor focused topic, though depending on how deep it goes. There are highly technical users who don't plan to contribute, but would like to understand the inner workings. Going too deep into that though I agree is more for those who work on the project. There should be a balance.

[ADubhlaoich]

I'm in agreement about that, actually: I really like the page, so it could simply be a case of reworking some of the content to make the reading experience less dense.

The NIC page has actually received the most glowing and detailed feedback of any documentation page on the entirety of the documentation website, so there's definitely some interest in this level of detail.

I definitely did an edit pass on it at least once, but I don't think I have for NGF's.

As "evergreen"¹ content, it can be continually refined as it will remain important at all stages of the product lifecycle.

Footnotes

1. Evergreen content remains "fresh" whenever consumed, like a documentary. Non-evergreen content would be instructions for a deprecated feature, or release notes for a long outdated version of the software. ↩