Adding Konnect Reference Platform

[rspurgeon]

Description

Adding the Konnect Reference platform landing page and associated documentation pages.

[netlify]

✅ Deploy Preview for kongdeveloper ready!

Name	Link
🔨 Latest commit	4ee6b10
🔍 Latest deploy log	https://app.netlify.com/sites/kongdeveloper/deploys/67ef25c73c286a0008588512
😎 Deploy Preview	https://deploy-preview-783--kongdeveloper.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[lena-larionova]

Partial review in the interest of making some progress.

[lena-larionova]

Suggested change

	Provides a complete guide for platform builders to to integrate {{site.konnect_product_name}} into their engineering
	Provides a complete guide for platform builders to integrate {{site.konnect_product_name}} into their engineering

[lena-larionova]

Suggested change

	governance, auditing, and GitOps based automations. The platform provides tools, examples, best practices, and documentation
	to guide you in on-boarding with {{site.konnect_short_name}}. You can choose how to use the components,
	individually or collectively, to fit your needs and engineering requirements.
	governance, auditing, and GitOps based automations.
	The platform provides resources to guide you in onboarding with {{site.konnect_short_name}}:
	* Tools
	* Examples
	* Best practices
	* Extensive documentation
	You can choose how to use the components,
	individually or collectively, to fit your needs and engineering requirements.

Trying to break up the wall of text a bit.

Maybe even something like "Custom-built" or "purpose-built tools"; "real life examples" to help flesh it out a bit.

[lena-larionova]

How about a "Learning path" h2 here?

[lena-larionova]

Suggested change

	This document outlines a suggested learning path for using the platform. Start by reading the FAQ section to
	understand its components and their purpose. Each component is then explained in detail, with relevant links to
	guide you on their usage. You can use individual components as needed, but if you decide the full platform is a
	good fit for your organization, follow the how-to guide to set
	up an instance connected to your {{site.konnect_short_name}} account and code repositories.
	To help you get started with the Reference Platform, you can follow this learning path:
	1. **Review FAQ:** Start by reading the FAQ section to
	understand the platform's components and their purpose.
	2. **Review components:** Learn about each component in detail, with relevant links to
	guide you on their use.
	3. **Set up an instance:** You can use individual components as needed, but if you decide the full platform is a
	good fit for your organization, follow the how-to guide to set
	up an instance connected to your {{site.konnect_short_name}} account and code repositories.

To make this easier to read and scan.

[lena-larionova]

Suggested change

	text: "Frequently Asked Questions"
	text: "Frequently asked questions"

We're using sentence case for headings (except on index pages)

[lena-larionova]

Suggested change

	Each organization defined in the `organizations` section, maps to a Konnect Organization. For each organization, you define
	authorization configurations and environments. Each environment will result in a set of configured resources with specific naming,
	metadata, and access control policies.
	Each organization defined in the `organizations` section maps to a Konnect Organization. For each organization, you define
	authorization configurations and environments. Each environment will result in a set of configured resources with specific naming,
	metadata, and access control policies.

[lena-larionova]

Suggested change

	Environments may be any conceptual grouping of resources the user desires. Typical examples include "dev" or "prod" engineering stages,
	but you may also desire to form environments around business units or products.
	Environments may be any conceptual grouping of resources that you want. Typical examples include "dev" or "prod" engineering stages,
	but you could also form environments around business units or products.

[lena-larionova]

Suggested change

	Konnect does not natively support the concept of environments. The orchestrator manages environments synthetically by
	prefixing resource names, applying labels, and setting different access control policies based on well known environment types.
	The orchestrator currently supports 2 environment types, DEV and PROD. Various resource configuration decisions are encoded into the Environment type,
	for example RBAC and portal settings. Environments also require a region configuration which must map to a Konnect supported geographic region.
	Konnect does not natively support the concept of environments. The orchestrator manages environments synthetically by
	prefixing resource names, applying labels, and setting different access control policies based on well known environment types.
	The orchestrator currently supports 2 environment types: DEV and PROD. Various resource configuration decisions are encoded into the Environment type,
	for example RBAC and portal settings. Environments also require a region configuration which must map to a Konnect supported geographic region.

[lena-larionova]

Suggested change

	## What specific Konnect resource are managed by the Konnect Orchestrator?
	## What specific Konnect resources are managed by the Konnect Orchestrator?

[lena-larionova]

I don't really understand this. Is this basically a for loop? It's hard to read as-is. I wonder if there's a way to display this as tree structure diagram.

[lena-larionova]

I started on a low-level page-by-page review, but there's a few things about this doc that I think we should look at before continuing that:

• I like the Kong Air intro page, it's short and sweet and to the point. However, I think this info actually belongs on the landing page.

The landing page:

• I know you want people to read the FAQs first, but that's not how people read docs. It's too much text to read with no context. I would move the other tiles up and put the FAQs at the very bottom.
• I want this page to introduce more concepts to me. What's the Konnect Orchestrator? What's Kong Air? You can spend more time introducing those items here, you don't have to limit that to just cards. You can add screenshots and images here to illustrate what these components are doing as well.
• For instance, you can use a staggered approach: https://kongdeveloper.netlify.app/premium-partners/

The FAQ page:

• This is a difficult page. I find it very hard to follow the information here. Additionally, there's parts of this page that are introductory (eg "What are the components of the Reference Platform"), which belong in more visible places.
• I'd want to see some of these FAQs moved to their specific pages. For instance, you have a lot of Orchestrator FAQs. Can you add those to the Orchestrator page as an FAQ entity instead?
• What is the format for the Konnect Orchestrator configuration? - this should be a reference table on the orchestrator page
• For anything that doesn't have an obvious page, they can stay here, but I'd group them by topic in H2s.
• There's a bunch of duplicate info here presented in different ways. For example:
  What Konnect resources are managed by the Konnect Orchestrator? vs What specific Konnect resources are managed by the Konnect Orchestrator? - why are these separated into two different sections?

Kong Orchestrator page:

• I like the page so far, but it's missing a lot of context. If you add the info from the FAQ, this page would be more complete.

How-to page:

• I didn't review this step-by-step since you're reworking it, but one of the first things that jumps out is the use of bullet points instead of ordered lists. If something should be done in order, it should be an ordered list instead.