When working with multiple clients and projects, what practices have you all found that work well for documenting system architecture and the corresponding gateway configuration? Outside of multiple Word docs, which I don't prefer, I haven't found a great system yet to highlight high-level configuration strategies and patterns, while also going into detail where needed when it comes to the gateway configuration in scale-out and other system architectures.
2 Likes
I'm interested in this as well... What would be cool is a Gateway Configuration report (that you can export as a PDF or some other format) that includes all of the gateway configurations that were committed (only non-default values), possibly the Network diagram if the GAN is used, and other useful data. Then you can look at the report, or, if its in a specific YAML-like syntax instead of PDF, do a diff between gateways to see their differences in configuration.
I think this would be easy(ier) to do in 8.3 - maybe that's a feature they will ship with. I would certainly use something like that.
If you make your v8.3 gateway a git repo, I would expect git diff to be useful.
3 Likes
Yeah, this is a really common pain point — especially once you’re juggling multiple clients and slightly different architectures.
What’s helped me is stopping the search for “one perfect doc” and instead breaking things up in a way that’s easy to consume and easy to maintain:
-
Start with a simple picture. A clear architecture diagram goes a long way. Nothing fancy — just enough to show how things talk to each other and where the gateways sit. Most people understand the system way faster from a picture than a wall of text.
-
Write down patterns, not every setting. I focus on explaining why a gateway is set up a certain way (public vs internal, scale-out approach, auth strategy, etc.) and reuse those explanations across projects.
-
Let the config speak for itself. The actual gateway config (YAML/JSON/etc.) becomes the detailed truth. The docs explain intent and gotchas, not every individual knob.
-
Use something lightweight. Markdown files in a repo or a simple wiki have been way easier to live with than Word docs. They’re faster to update and don’t feel like a chore.
-
Call out what’s different per client. Instead of rewriting everything, I keep a short “client-specific notes” section that highlights deviations from the standard setup.
Once I shifted to “clear enough to understand, not perfect,” documentation stopped being this massive burden and actually started helping people.
7 Likes