Skip to content

Improve information architecture - move swaggers to a new label #6583

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 6 commits into
base: master
Choose a base branch
from
Open

Improve information architecture - move swaggers to a new label #6583

wants to merge 6 commits into from

Conversation

letzya
Copy link
Collaborator

@letzya letzya commented Jun 24, 2025 •
edited by github-actions bot
Loading

User description

Preview Link

Checklist

  • Added a preview link
  • Reviewed AI PR Agent suggestions
  • For Tyk Members - Added Jira DX PR ticket to the subject
  • For Tyk Members - Added the appropriate release labels (for fixes add the latest release)

New Contributors

PR Type

documentation, enhancement

Description

  • Refactored Developer Support and Reference navigation structure

  • Moved Inclusive Naming Policy to a dedicated page

  • Split and clarified docs contribution and naming policy content

  • Fixed numerous typos and improved terminology consistency

Changes walkthrough 📝

Relevant files
Enhancement
1 files
menu.yaml
Major navigation restructure for Developer Support and Reference
sections
 +47/-36 
Documentation
22 files
contributing.md
Streamlined contribution guide and moved naming policy content
 +3/-113 
inclusive-naming-policy.md
Added new Inclusive Naming Policy documentation page         
+112/-0 
deprecation.md
Updated title and added tags for Deprecation and EOL Policy
 +2/-1     
support.md
Retitled page to "Support SLA Policy"                                       
+1/-1     
upgrading.md
Cleaned up aliases and improved metadata                                 
+1/-8     
filters.md
Corrected "Middlewares" to "Middleware" in tags and keywords
 +2/-2     
operator.md
Clarified language about API definition and middleware     
+1/-1     
data-graph.md
Improved clarity and inclusivity in DataSources section   
+5/-5     
golang.md
Standardized "middleware" terminology and improved explanations
 +2/-2     
rich-plugins.md
Enhanced explanations and added anchor tags for sections 
+7/-6     
traffic-transformation.md
Retitled page to use singular "Middleware"                             
+1/-1     
go-templates.md
Fixed typo in "blog post" reference                                           
+1/-1     
tyk-oss-chart.md
Standardized "middleware" terminology in mounting instructions
 +2/-2     
api-def-graphql.md
Corrected "middlewares" to "middleware" in GraphQL config
 +1/-1     
mdcb-config.md
Standardized "data planes" terminology in MDCB config       
+2/-2     
x-tyk-gateway.md
Standardized "middleware" terminology in context variables section
 +1/-1     
custom-developer-portal.md
Added anchor for "Building a Portal" section                         
+1/-1     
tib-rest-api.md
Removed unnecessary anchor from "List Profiles" section   
+1/-1     
archived.md
Fixed typos and improved terminology in release notes       
+2/-2     
dashboard.md
Fixed typos, improved terminology, and clarified explanations
 +8/-7     
gateway.md
Fixed typos, improved terminology, and clarified explanations
 +21/-28 
portal.md
Fixed typo in "blog posts" and improved clarity                   
+1/-1     
Need help?
  • Type /help how to ... in the comments thread for any questions about PR-Agent usage.
  • Check out the documentation for more information.
    •

    @github-actions GitHub Actions
    Copy link
    Contributor

    ⚠️ Deploy preview for PR #6583 did not become live after 3 attempts.
    Please check Netlify or try manually: Preview URL

    @github-actions GitHub Actions
    Copy link
    Contributor

    PR Reviewer Guide 🔍

    Here are some key observations to aid the review process:

    ⏱️ Estimated effort to review: 3 🔵🔵🔵⚪⚪
    🧪 No relevant tests
    🔒 No security concerns identified
    ⚡ Recommended focus areas for review

    Content Relocation

    The inclusive naming policy content has been moved to a dedicated page. Review to ensure that all relevant cross-references and links are updated accordingly and that no important context was lost in the transition.

     
    ---
title: "Contributing to Tyk Docs"
date: 2024-05-17T15:51:00+01:00
tags: [ "Docs contribution", "contribution guides", "Tyk Docs contribution" ]
description: "Explains how to contribute Tyk docs repository"
aliases:
   - /contribute
---

We appriciate any form of engagement and contribution to our documentation. You can do it in a few ways:
- [Report an error](https://github.com/TykTechnologies/tyk-docs/issues) in our Github repo.
- [Suggest/request an improvement](https://github.com/TykTechnologies/tyk-docs/issues) in our Github repo.
- Update the code yourself:
  1. If you want to be even more involved, you are welcomed to [submit PR](https://github.com/TykTechnologies/tyk-docs/pulls) directly in our [docs repo](https://github.com/TykTechnologies/tyk-docs/).
  2. In order for you need to find the page that needs editing in the actual [GH docs repo](https://github.com/TykTechnologies/tyk-docs/), the best way would be to copy a sentence from that HTML page on the [docs website](https://tyk.io/docs) and look it up it using the Github search box, on the top left corner. (Since the structure of our docs is not the same as the structure in the rendered docs website, we can't easily link you to this page).
- Post a message in our [community forum](https://community.tyk.io/)

Our docs are compiled using the [Hugo static site generator](https://gohugo.io/).

The [Readme](https://github.com/TykTechnologies/tyk-docs#readme) has details of how to construct docs pages.

This document is intended for Tyk users, contributors, and anyone interested in our commitment to inclusive language within Tyk's documentation and product interfaces.
    Navigation Structure Refactor

    The navigation structure for Developer Support and Reference sections has been significantly refactored. Validate that all menu items are correctly categorized, visible as intended, and that no important links are missing or duplicated.

     
              category: Page
          show: True

    - title: "Manage Distributed Gateways"
      path: /api-management/mdcb
      category: Page
      show: True

- title: "Reference"
  category: Label
  show: True
  menu:
    - title: "Environment Variables and Configs"
      category: Directory
      show: True
      menu:
      - title: "Gateway"
        path: /tyk-oss-gateway/configuration
        category: Page
        show: True
      - title: "Dashboard"
        path: /tyk-dashboard/configuration
        category: Page
        show: True
      - title: "Pump"
        path: /tyk-pump/tyk-pump-configuration/tyk-pump-environment-variables
        category: Page
        show: True
      - title: "Enterprise Developer Portal"
        path: /product-stack/tyk-enterprise-developer-portal/deploy/configuration
        category: Page
        show: True
      - title: "Multi Data Center Bridge"
        path: /tyk-multi-data-centre/mdcb-configuration-options
        category: Page
        show: True
      - title: "Tyk Identity Broker"
        path: /tyk-configuration-reference/tyk-identity-broker-configuration
        category: Page
        show: True
    - title: "API Documentation"
      category: Directory
      show: True
      menu:
      - title: "Overview"
        path: /tyk-apis
        category: Page
        show: True
      - title: "Gateway"
        path: /tyk-gateway-api
        category: Page
        show: True
      - title: "Dashboard"
        path: /tyk-dashboard-api
        category: Page
        show: True
      - title: "Dashboard Admin"
        path: /dashboard-admin-api
        category: Page
        show: True
      - title: "Multi Data Center Bridge"
        path: /tyk-mdcb-api
        category: Page
        show: True
      - title: "Enterprise Developer Portal"
        path: /product-stack/tyk-enterprise-developer-portal/api-documentation/tyk-edp-api
        category: Page
        show: True
      - title: "Enterprise Developer Portal Admin"
        path: /product-stack/tyk-enterprise-developer-portal/api-documentation/list-of-endpoints/portal-1.13.0-list-of-endpoints
        category: Page
        show: True
      - title: "Tyk Identity Broker"
        path: /tyk-identity-broker/tib-rest-api
        category: Page
        show: True

- title: "Developer Support"
  category: Label
  show: True
  menu:
    - title: "Release Notes"
      category: Directory
      show: True
      menu:
      - title: "Latest Tyk Releases"
        path: /developer-support/release-notes/overview
        category: Page
        show: True
      - title: "Gateway"
        path: /developer-support/release-notes/gateway
        category: Page
        show: True
      - title: "Dashboard"
        path: /developer-support/release-notes/dashboard
        category: Page
        show: True
      - title: "Pump"
        path: /developer-support/release-notes/pump
        category: Page
        show: True
      - title: "Sync"
        path: /developer-support/release-notes/sync
        category: Page
        show: True
      - title: "Multi Data Center Bridge"
        path: /developer-support/release-notes/mdcb
        category: Page
        show: True
      - title: "Enterprise Developer Portal"
        path: /developer-support/release-notes/portal
        category: Page
        show: True
      - title: "Tyk Operator"
        path: /developer-support/release-notes/operator
        category: Page
        show: True
      - title: "Tyk Chart"
        path: /developer-support/release-notes/helm-chart
        category: Page
        show: True
      - title: "Tyk Identity Broker"
        path: /developer-support/release-notes/tib
        category: Page
        show: True
      - title: "Tyk Cloud"
        path: /developer-support/release-notes/cloud
        category: Page
        show: True
      - title: "Archived Releases"
        path: /developer-support/release-notes/archived
        category: Page
        show: True
    - title: "Upgrading Guide"
      path: /developer-support/upgrading
      category: Page
      show: True
    - title: "Frequently Asked Questions"
      path: /developer-support/faq
      category: Page
      show: True
    - title: "Tyk Releases Policy"
      category: Directory
      show: True
      menu:
        - title: "Long Term Support Release"
          path: /developer-support/release-types/long-term-support
          category: Page
          show: True
        - title: "Early access feature"
          path: /developer-support/release-types/early-access-feature
          category: Page
          show: True
        - title: "Lab Release"
          path: /developer-support/release-types/lab-release
          category: Page
          show: True
        - title: "FIPS Release"
          path: /developer-support/release-types/fips-release
          category: Page
          show: True
    - title: "Deprecation and EOL Policy"
      path: /developer-support/deprecation
      category: Page
      show: True
    - title: "Support SLA Policy"
      path: /developer-support/support
      category: Page
      show: True
    - title: "Community Support"
      path: /developer-support/community
      category: Page
      show: True
    - title: "Inclusive Naming Policy"
      path: /developer-support/inclusive-naming-policy
      category: Page
      show: True
    - title: "Contributing to Tyk docs"
      category: Directory
      show: True
      menu:
        - title: "Overview"
          path: /developer-support/contributing
          category: Page
          show: True
        - title: "UI Example: Pill Label shortcode"
    New Policy Page

    A new Inclusive Naming Policy page has been introduced. Ensure the content is accurate, up-to-date, and consistent with organizational guidelines, and that all referenced configuration parameters and links are correct.

     
    ---
date: 2017-03-27T16:05:33+01:00
title: "Inclusive Naming Policy"
tags: [ "Inclusive Naming Initiative", "Inclusivity", "Inclusive" ]
aliases:
  - /developer-support/documentation-projects/inclusive-naming
---

In June, 2024, we announced the launch of our *Inclusive Naming* project, dedicated to updating our documentation and aligning with the [Inclusive Naming Initiative (INI)](https://inclusivenaming.org). This initiative reflects our commitment to fostering an inclusive and respectful environment for our users and within our company.

The [Inclusive Naming Initiative](https://inclusivenaming.org/) is a community-driven effort to promote and standardize the use of inclusive language in software and documentation. By adhering to their guidelines, we aim to eliminate terms that can be considered exclusionary, offensive, or insensitive and replace them with language that is respectful and welcoming to all.

## Purpose

Our commitment to diversity, equity, and inclusion is foundational to our values. By updating our documentation to comply with the *Inclusive Naming Initiative (INI)*, we are taking a significant step towards ensuring that our language reflects our dedication to inclusivity. This project will help us:

- **Create a more welcoming environment**: By using inclusive language, we create a space where everyone feels valued and respected.
- **Enhance accessibility**: Clear and inclusive documentation improves accessibility for all users, regardless of their background or identity.

## Tier 1 word list

INI sorts terms into word lists, considering both the severity of the term and the level of scrutiny it has received. [INI Tier 1 words](https://inclusivenaming.org/word-lists/tier-1) are considered critical and are recommended to be replaced immediately.

INI has identified that terms included in this list have one or all of the following attributes:

- Strong social consensus within the software development community on replacements
- Are identified by the INI as high-severity terms in need of immediate replacement
- Terms where the impact of change or removal is low: for example, there is little entanglement in low-level systems or standardized language set by standards bodies
- Have passed through all the review stages in Tiers 2 and 3

## Phase #1: Review of Tyk Documentation for Tier 1 Words

An initial review of the Tyk documentation was conducted in April 2024 to check which tier 1 words can be replaced, which can't, and why.

### Findings and planning
The main findings of the review are:

1. **Explanatory content with INI tier 1 words**: The content on these pages can be easily rephrased and is now completed.
2. **Configuration parameters containing INI tier 1 words**:
   - Some *INI tier 1 words* are embedded in the code as part of the name of parameters, fields, and keywords.
   - These words are sourced from Tyk products, and third-party libraries, and tooling, e.g. Redis.
   - Possible actions:
     - Being part of the source code, we can't simply rephrase and use a different terminology. Such change requires following a deprecation process to ensure there are no breaking changes for our users.
     - For now, we can minimize their usage and rephrase the explanatory content to use inclusive words.


## Phase #2: Removing Tier 1 words from Tyk documentation

In June 2024, based on the review we executed the planned changes to the content in our [documentation](https://github.com/tykTechnologies/tyk-docs/).

### Status update
This is the update on the status of our documentation
1. **Regular explanatory content with INI tier 1 words**: Content in the documentation has been rephrased and the work is now completed. 
2. **Configuration parameters containing INI tier 1 words**: These words are still in our docs, however, we minimized their usage and rephrased their explanatory content to use inclusive words.
   - **Tyk products**: These words are still in our docs, however, Tyk aims to gradually replace them (in a backward-compatible way) and update the docs accordingly.
   - **Third-party and dependencies**: There's nothing much we can do at the moment except wait for them to replace these parameters, however, we are committed to updating our docs once this gets done.

For your records, the following sections highlight the existing *INI tier 1 words* in our docs, per Tyk component:

#### Tyk Gateway

**Config parameters**

- [allow_master_keys]({{< ref "tyk-oss-gateway/configuration#allow_master_keys" >}})
- [analytics_storage.master_name]({{< ref "tyk-oss-gateway/configuration#analytics_storagemaster_name" >}})
- [cache_storage.master_name]({{< ref "tyk-oss-gateway/configuration#cache_storagemaster_name" >}})
- [storage.master_name]({{< ref "tyk-oss-gateway/configuration#storagemaster_name" >}})
- [slave_options]({{< ref "tyk-oss-gateway/configuration#slave_options" >}})
- [blacklisted_ips]({{< ref "api-management/gateway-config-tyk-classic#ip-access-control" >}})
- [disable_ports_whitelist]({{< ref "key-concepts/tcp-proxy#allowing-specific-ports" >}})
- [enable_ip_blacklisting]({{< ref "api-management/gateway-config-tyk-classic#ip-access-control" >}})
- [ports_whitelist]({{< ref "key-concepts/tcp-proxy#allowing-specific-ports" >}})

#####  Tyk Classic API Definition {#gw-classic-api-definition}

The [Tyk Gateway OpenAPI Document](https://github.com/TykTechnologies/tyk-docs/blob/master/tyk-docs/assets/others/gateway-swagger.yml) (Tyk Gateway swagger), includes references to the following Tyk Classic API Definition parameters:

- [version_data.versions.{version-name}.extended_paths.black_list]({{< ref "api-management/traffic-transformation/block-list#api-definition" >}}). There is also a parameter with equivalent functionality under the `paths` object (`version_data.versions.{version_name}.paths.black_list`).
- [version_data.versions.{version-name}.extended_paths.white_list]({{< ref "api-management/traffic-transformation/allow-list#api-definition" >}}). There is also a parameter with equivalent functionality under the `paths` object (`version_data.versions.{version_name}.paths.while_list`).

#### Tyk Dashboard

**Config parameters**
- [enable_master_keys]({{< ref "tyk-dashboard/configuration#enable_master_keys" >}})
- [redis_master_name]({{< ref "tyk-dashboard/configuration#redis_master_name" >}})

**Tyk Classic API Definition**

The [Tyk Dashboard OpenAPI Document](https://github.com/TykTechnologies/tyk-docs/blob/master/tyk-docs/assets/others/dashboard-swagger.yml) (Tyk Dashboard swagger), contains references to [the parameters from the above Tyk Classic API Definition list]({{< ref "#gw-classic-api-definition" >}}).

**Dashboard UI**

The Tyk Classic APIs *Endpoint Designer* shows configuration of [blacklist]({{< ref "api-management/traffic-transformation/block-list#api-designer" >}}) and [whitelist]({{< ref "api-management/traffic-transformation/allow-list#api-definition" >}}) middleware plugins.

#### Tyk MDCB

The following MDCB configuration parameters contain tier 1 word occurrences:
- [analytics_storage.master_name]({{< ref "tyk-multi-data-centre/mdcb-configuration-options#analytics_storagemaster_name" >}})
- [storage.master_name]({{< ref "tyk-multi-data-centre/mdcb-configuration-options#storagemaster_name" >}})

#### Tyk Pump

The following Tyk Pump configuration parameters contain tier 1 word occurrences:
- [analytics_storage_config.master_name]({{< ref "tyk-pump/tyk-pump-configuration/tyk-pump-environment-variables#analytics_storage_configmaster_name" >}})

#### Third-party dependencies 

Content contains *INI Tier 1 word* occurrences due to the following external dependencies:
- Links to Tyk Component GitHub repositories with a default branch set as `master`. 
- Tyk Gateway and Tyk Pump content use Redis terminology for `master` in relation to key storage and analytics. 
- Tyk Classic Developer Portal provides [documentation]({{< ref "tyk-developer-portal/tyk-portal-classic/keycloak-dcr" >}}) that explains how to integrate Tyk with Keycloak using the [OpenID Connect Dynamic Client Registration](https://tools.ietf.org/html/rfc7591) protocol. The example in the guide uses the Keycloak default `master` realm.
- Tyk Bitnami Helm charts use a service with a DNS name of *tyk-redis-master.tyk.svc*.

    @github-actions GitHub Actions
    Copy link
    Contributor

    PR Code Suggestions ✨

    No code suggestions found for the PR.

    @netlify Netlify
    Copy link

    netlify bot commented Jun 24, 2025 •
    edited
    Loading

    ✅ PS. Add to the end of url /docs/nightly

    Name Link
    🔨 Latest commit 07c2340
    🔍 Latest deploy log https://app.netlify.com/projects/tyk-docs/deploys/685bf7078340a500078c54aa
    😎 Deploy Preview https://deploy-preview-6583--tyk-docs.netlify.app
    📱 Preview on mobile
    Toggle QR Code...

    QR Code

    Use your smartphone camera to open QR code link.

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

    yurisasuke
    yurisasuke reviewed Jun 25, 2025
    View reviewed changes
    tyk-docs/content/api-management/plugins/rich-plugins.md
    @@ -2308,7 +2308,7 @@ In this tutorial we learned how Tyk gRPC plugins work. For a production-level se
    [3]: /img/dashboard/system-management/api_settings.png
    [4]: /img/dashboard/system-management/plugin_options.png

    ### Create Custom Authentication Plugin with .NET
    ### Create Custom Authentication Plugin with .NET {#create-custom-auth-plugin-with-dotnet}
    Copy link
    Member

    @yurisasuke yurisasuke Jun 25, 2025 •
    edited
    Loading

    Choose a reason for hiding this comment

    The reason will be displayed to describe this comment to others. Learn more.

    In places where create-custom-auth-plugin-with-net was used we need to change them to create-custom-auth-plugin-with-dotnet to make the htmltest ci to pass check #6586

    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Reviewers

    @yurisasuke yurisasuke yurisasuke left review comments

    @sharadregoti sharadregoti Awaiting requested review from sharadregoti

    At least 1 approving review is required to merge this pull request.

    Assignees
    No one assigned
    Labels
    release-5.8 Review effort 3/5
    Projects
    None yet
    Milestone
    No milestone
    Development

    Successfully merging this pull request may close these issues.
    3 participants
    @letzya @yurisasuke @buger