Merging to release-5.4: [DX-1520] Add explanation to the use of catalogue and catalog (#5084)

[buger]

User description

DX-1520 Add explanation to the use of catalogue and catalog (#5084)

• Add explanation to the use of catalogue and catalog

• Update tyk-docs/content/tyk-apis/tyk-portal-api/portal-documentation.md

• Update tyk-docs/content/tyk-portal-api.md

• Update portal-documentation.md

---

PR Type

Documentation, Enhancement

---

Description

• Updated the title and description of the portal-documentation.md file to clarify API publishing endpoints and added a note on the use of British and American English spellings.
• Changed the code block languages for sample requests and responses in portal-documentation.md and portal-keys.md to appropriate formats like http, json, and yaml.
• Updated the title and description of the tyk-portal-api.md file to better describe the Classic Portal API.
• Revised menu titles and paths in menu.yaml for improved clarity and navigation.

---

Changes walkthrough 📝

Relevant files

Documentation

portal-documentation.md Clarify API publishing endpoints and spelling conventions tyk-docs/content/tyk-apis/tyk-portal-api/portal-documentation.md Updated title and description to clarify API publishing endpoints. Added a note on the use of British and American English spellings. Changed code block languages for sample requests and responses. +27/-12  portal-keys.md Update code block languages for portal keys                            tyk-docs/content/tyk-apis/tyk-portal-api/portal-keys.md Changed code block languages for sample requests and responses. +13/-13  tyk-portal-api.md Update Classic Portal API title and description                    tyk-docs/content/tyk-portal-api.md Updated title and description for the Classic Portal API. Simplified the introduction to the API endpoints. +4/-7      menu.yaml Revise menu titles and paths for clarity                                  tyk-docs/data/menu.yaml Updated menu titles and paths for better clarity. +8/-8

---

💡 PR-Agent usage:
Comment /help on the PR to get a list of all available PR-Agent tools and their descriptions

[github-actions]

PR Reviewer Guide 🔍

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Key issues to review Spelling Consistency The note on spelling consistency is helpful, but it might be clearer to provide specific examples of where British and American English differ in the context of the API or UI, rather than a general statement. Code Block Language The change from generic code blocks to specific languages (http, json, yaml) is good for readability and syntax highlighting. However, ensure that all code blocks in the document follow this new standard for consistency.

[github-actions]

PR Code Suggestions ✨

Category	Suggestion	Score
Best practice	Correct the formatting of the HTTP headers in the documentation examples Ensure that the API endpoint examples in the documentation are correctly formatted to enhance readability and standard compliance. Specifically, the authorization header should be properly formatted with a space after the colon. tyk-docs/content/tyk-apis/tyk-portal-api/portal-documentation.md [115] -authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8 +authorization: 7a7b140f-2480-4d5a-4e78-24049e3ba7f8 Suggestion importance[1-10]: 9 Why: Correctly formatting the HTTP headers improves readability and ensures standard compliance, which is important for users following the documentation.	9
	Use Markdown syntax for notes to maintain consistency and readability Replace the direct HTML note block with a Markdown equivalent using blockquotes or a custom Markdown extension if supported, to keep the document format consistent and clean. tyk-docs/content/tyk-apis/tyk-portal-api/portal-documentation.md [11-24] -{{< note success >}} -{{< /note >}} +> **Important Note on Spelling:** +> +> While our documentation now uses American English, the product itself, including UI, configuration fields, environment variables, and APIs endpoints, retain British English spellings. When interacting with the product, please continue using the British English spellings as they appear in the interface and API. (This means that for existing users nothing has changed). Suggestion importance[1-10]: 8 Why: Using Markdown syntax for notes enhances consistency and readability, making the document easier to maintain and understand. This is a good practice for documentation.	8
Consistency	Standardize the use of code block annotations for consistency It's recommended to use consistent code block annotations for all HTTP and JSON examples. The PR introduces different formats (http and json), which should be standardized across the documentation. tyk-docs/content/tyk-apis/tyk-portal-api/portal-documentation.md [112-120] ```http -```json +```http Suggestion importance[1-10]: 8 Why: Consistent use of code block annotations enhances the readability and professionalism of the documentation. This is important for maintaining a high standard of documentation quality.	8
Maintainability	Remove unnecessary HTML line break tags from Markdown content Consider removing the unnecessary tags used for spacing in Markdown files. Markdown provides other ways to manage spacing and layout that are more semantically appropriate, such as using additional newlines or manipulating with CSS in HTML contexts. tyk-docs/content/tyk-apis/tyk-portal-api/portal-documentation.md [9-19] -</br> -</br> +(Remove the lines) Suggestion importance[1-10]: 7 Why: Removing unnecessary HTML tags improves the maintainability and readability of the Markdown file. However, this is a minor improvement and does not address any critical issues.	7

[netlify]

✅ PS. Pls add /docs/nightly to the end of url

Name	Link
🔨 Latest commit	3910d89
🔍 Latest deploy log	https://app.netlify.com/sites/tyk-docs/deploys/66960b89377d620008479952
😎 Deploy Preview	https://deploy-preview-5086--tyk-docs.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.

[netlify]

✅ PS. Pls add /docs/nightly to the end of url

Name	Link
🔨 Latest commit	3910d89
🔍 Latest deploy log	https://app.netlify.com/sites/tyk-docs/deploys/66960b89377d620008479952
😎 Deploy Preview	https://deploy-preview-5086--tyk-docs.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.