Tenant specific documentation

[Starefossen]

Appetite

Two persons for one week.

Essences

We have two challenges with the current documentation:

1. We have a lot of documentation that is not relevant for all tenants.
2. We are using placeholders <tenant> in the documentation to make the documentation generic.

nais is a platform with a lot of features and history. Much of what we provide is not (yet) relevant for all tenants through our naas offering. This is a problem because it makes it harder to find the relevant documentation and for tenants to understand what they can use and if there are any limitations specific to their tenant.

Since we are using placeholders in the documentation, it is not possible to link to tenant specific resources. This is a problem because it makes it harder to access the correct resource and a majority of our users are not aware of what their tenant is called (this is primarily an issue within nav).

Some links and names are not using placeholders and are hard-coded to a specific tenant (nav in most cases).

Non Goals

• Duplicate the source of the documentation.
• Replace mkdocs with another tool.

Proposed Solution

We can use the mkdocs-macros-plugin to create a macro that will only render a section of the documentation if the tenant is in the list of tenants that should see the section. We can also use propper tenant names instead of the <tenant> placeholder when linking to relevant tenant specific resource.

mkdocs-macros-plugin is a plugin for mkdocs that allows us to create variables and macros by leveraging the jinja2 templating language. It is installed as a plugin in the mkdocs.yml file like this:

plugins:
  …
  - macros

Then we can build the documentation for each tenant and publish it to a tenant specific url, e.g. https://docs.<tenant>.cloud.nais.io and keeping https://docs.nais.io as the default documentation for nav. When this is enabled, we can remove the <tenant> placeholder from the documentation and replace it with the correct tenant name like this:

This is the documentation for the {{ tenant_name }} tenant.

This will render as this for the nav tenant:

This is the documentation for the nav tenant.

[frodesundby]

Det kommer en sak som handler om å se på dokumentasjonen vår som helhet og omskrive den i henhold til Tenant-spesifikk dokumentasjon er noe av det vi har lyst til å se på i den forbindelse.

[jhrv]

done