Merge pull request #1269 from Unleash/docs/diataxis-restructure

Docs: restructure documentation
Unleash · Jan 26, 2022 · 452416c · 452416c
2 parents 025ba0e + bb37141
commit 452416c
Show file tree

Hide file tree

Showing 19 changed files with 428 additions and 235 deletions.
diff --git a/website/docs/addons/addons.md b/website/docs/addons/addons.md
@@ -1,6 +1,6 @@
 ---
 id: index
-title: Introduction
+title: Addons
 ---
 
 > This feature was introduced in _Unleash v3.11.0_.

diff --git a/website/docs/advanced/api_access.md b/website/docs/advanced/api_access.md
@@ -1,13 +1,13 @@
 ---
 id: api_access
-title: API Access
+title: How to use the Admin API
 ---
 
 It is possible to integrate directly with the Admin API. In this guide we will explain all the steps to set it up.
 
 ## Step 1: Create API token {#step-1-create-api-token}
 
-Please refer to [Create token](../user_guide/api-token) on how to create an API token. You'll need a token with `Admin` level access for this to work.
+Please refer to [_how to create API tokens_](../user_guide/api-token) on how to create an API token. You'll need a token with `Admin` level access for this to work.
 
 Please note that it may take up to 60 seconds for the new key to propagate to all Unleash instances due to eager caching.
 

diff --git a/website/docs/advanced/sso-google.md b/website/docs/advanced/sso-google.md
@@ -1,6 +1,6 @@
 ---
 id: sso-google
-title: SSO - Google (deprecated)
+title: "[Deprecated] How to add SSO with Google"
 ---
 
 > Single Sign-on via the Google Authenticator provider is deprecated. We recommend using [OpenId Connect](./sso-open-id-connect.md) instead.

diff --git a/website/docs/advanced/sso-open-id-connect.md b/website/docs/advanced/sso-open-id-connect.md
@@ -1,6 +1,6 @@
 ---
 id: sso-open-id-connect
-title: SSO - OpenId Connect
+title: How to add SSO with OpenId Connect
 ---
 
 > The **Single-Sign-On capability** is only available for customers on the Enterprise subscription. Check out the [Unleash plans](https://www.getunleash.io/plans) for details.

diff --git a/website/docs/advanced/sso-saml-keycloak.md b/website/docs/advanced/sso-saml-keycloak.md
@@ -1,6 +1,6 @@
 ---
 id: sso-saml-keycloak
-title: SSO - SAML 2.0 Keycloak
+title: How to add SSO with SAML 2.0 Keycloak
 ---
 
 > The **Single-Sign-On capability** is only available for customers on the Enterprise subscription. Check out the [Unleash plans](https://www.getunleash.io/plans) for details.

diff --git a/website/docs/advanced/sso-saml.md b/website/docs/advanced/sso-saml.md
@@ -1,6 +1,6 @@
 ---
 id: sso-saml
-title: SSO - SAML 2.0 Okta
+title: How to add SSO with SAML 2.0 Okta
 ---
 
 > The **Single-Sign-On capability** is only available for customers on the Enterprise subscription. Check out the [Unleash plans](https://www.getunleash.io/plans) for details.

diff --git a/website/docs/integrations/integrations.md b/website/docs/integrations/integrations.md
@@ -2,8 +2,21 @@
 id: integrations
 title: External Integrations and plugins
 ---
+import DocCardList from '@theme/DocCardList';
+import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
 
-Available integrations with Unleash
+
+Unleash can also integrate with other systems in different ways.
+
+## Official integrations
+
+Unleash provides these official integrations:
+
+<DocCardList items={useCurrentSidebarCategory().items}/>
+
+## Community-contributed integrations:
+
+Our wonderful community has also created the following integrations:
 
 - [Vue Unleash plugin](https://github.com/crishellco/vue-unleash)
 - [Quarkus](https://github.com/quarkiverse/quarkus-unleash)

diff --git a/website/docs/sdks/java.md b/website/docs/sdks/java.md
@@ -57,7 +57,7 @@ Read more about the [Unleash architecture](https://www.unleash-hosted.com/articl
 
 ## Step 4: Provide Unleash Context {#step-4-provide-unleash-context}
 
-It is the client SDK that computes whether a feature toggle should be considered enabled or disabled for specific use request. This is the job of the [activation strategies](../user_guide/control_rollout), which are implemented in the client SDK.
+It is the client SDK that computes whether a feature toggle should be considered enabled or disabled for specific use request. This is the job of the [activation strategies](../user_guide/activation-strategies.md), which are implemented in the client SDK.
 
 The activation strategies is an implementation of rules based on data, which you provide as part of the Unleash Context.
 

diff --git a/website/docs/sdks/php.md b/website/docs/sdks/php.md
@@ -56,7 +56,7 @@ Read more about the [Unleash architecture](https://www.unleash-hosted.com/articl
 
 ## Step 4: Provide Unleash Context {#step-4-provide-unleash-context}
 
-It is the client SDK that computes whether a feature toggle should be considered enabled or disabled for specific use request. This is the job of the [activation strategies](../user_guide/control_rollout), which are implemented in the client SDK.
+It is the client SDK that computes whether a feature toggle should be considered enabled or disabled for specific use request. This is the job of the [activation strategies](../user_guide/activation-strategies.md), which are implemented in the client SDK.
 
 The activation strategies is an implementation of rules based on data, which you provide as part of the Unleash Context.
 

diff --git a/website/docs/user_guide/activation-strategies.md b/website/docs/user_guide/activation-strategies.md
@@ -7,7 +7,13 @@ It is powerful to be able to turn a feature on and off instantaneously, without
 
 The definition of an activation strategy lives in the Unleash API and can be created via the Unleash UI. The implementation of activation strategies lives in various client implementations.
 
-Unleash comes with a few common activation strategies. Some of them require the client to provide the [unleash-context](unleash-context.md), which gives the necessary context for Unleash.
+Unleash comes with a few common activation strategies. Some of them require the client to provide the [unleash-context](unleash-context.md), which gives the necessary context for Unleash. The built-in activation strategies are:
+
+- [Standard](#standard)
+- [UserIDs](#userids)
+- [Gradual Rollout](#gradual-rollout)
+- [IPs](#ips)
+- [Hostnames](#hostnames)
 
 ## Standard {#standard}
 
@@ -80,7 +86,18 @@ This strategy has the following modelling name in the code:
 
 - **applicationHostname**
 
-## gradualRolloutUserId (DEPRECATED from v4) - Use Gradual rollout instead {#gradualrolloutuserid-deprecated-from-v4---use-gradual-rollout-instead}
+
+## Multiple activation strategies {#multiple-activation-strategies}
+
+You can apply as many activation strategies to a toggle as you want. When a toggle has multiple strategies, Unleash will check each strategy in isolation. If any one of the strategies would enable the toggle for the current user, then the toggle is enabled.
+
+As an example, consider a case where you want to roll a feature out to 75% of your users. However, you also want to make sure that the you and your product lead get access to the feature. To achieve this, you would apply a **gradual rollout** strategy and set it to 75%. Additionally, you would add a **user IDs** strategy and add `engineer@mycompany.com` and `productlead@mycompany.com`.
+
+![A feature toggle with two active strategies: a user ID strategy and a gradual rollout strategy. The strategies are configured as described in the preceding paragraph.](/img/control_rollout_multiple_strategies.png)
+
+## Deprecated strategies
+
+### gradualRolloutUserId (DEPRECATED from v4) - Use Gradual rollout instead {#gradualrolloutuserid-deprecated-from-v4---use-gradual-rollout-instead}
 
 The `gradualRolloutUserId` strategy gradually activates a feature toggle for logged-in users. Stickiness is based on the user ID. The strategy guarantees that the same user gets the same experience every time across devices. It also assures that a user which is among the first 10% will also be among the first 20% of the users. That way, we ensure the users get the same experience, even if we gradually increase the number of users exposed to a particular feature. To achieve this, we hash the user ID and normalize the hash value to a number between 1 and 100 with a simple modulo operator.
 
@@ -93,7 +110,7 @@ Starting from v3.x all clients should use the 32-bit [MurmurHash3](https://en.wi
 - percentage - _The percentage (0-100) you want to enable the feature toggle for._
 - groupId - _Used to define an activation group, which allows you to correlate rollout across feature toggles._
 
-## gradualRolloutSessionId (DEPRECATED from v4) - Use Gradual rollout instead {#gradualrolloutsessionid-deprecated-from-v4---use-gradual-rollout-instead}
+### gradualRolloutSessionId (DEPRECATED from v4) - Use Gradual rollout instead {#gradualrolloutsessionid-deprecated-from-v4---use-gradual-rollout-instead}
 
 Similar to `gradualRolloutUserId` strategy, this strategy gradually activates a feature toggle, with the exception being that the stickiness is based on the session IDs. This makes it possible to target all users (not just logged-in users), guaranteeing that a user will get the same experience within a session.
 
@@ -102,7 +119,7 @@ Similar to `gradualRolloutUserId` strategy, this strategy gradually activates a
 - percentage - _The percentage (0-100) you want to enable the feature toggle for._
 - groupId - _Used to define an activation group, which allows you to correlate rollout across feature toggles._
 
-## gradualRolloutRandom (DEPRECATED from v4) - Use Gradual rollout instead {#gradualrolloutrandom-deprecated-from-v4---use-gradual-rollout-instead}
+### gradualRolloutRandom (DEPRECATED from v4) - Use Gradual rollout instead {#gradualrolloutrandom-deprecated-from-v4---use-gradual-rollout-instead}
 
 The `gradualRolloutRandom` strategy randomly activates a feature toggle and has no stickiness. We have found this rollout strategy very useful in some scenarios, especially when we enable a feature which is not visible to the user. It is also the strategy we use to sample metrics and error reports.
 

diff --git a/website/docs/user_guide/control-rollout.md b/website/docs/user_guide/control-rollout.md
diff --git a/website/docs/user_guide/create-feature-toggle.md b/website/docs/user_guide/create-feature-toggle.md
@@ -1,6 +1,6 @@
 ---
 id: create_feature_toggle
-title: Create a feature toggle
+title: How to create a feature toggle
 ---
 
 In this guide you will learn how to create your first feature toggle using Unleash.
@@ -32,7 +32,7 @@ The toggle is now created and ready to be used. The toggle does not have any met
 
 ## Step 4: Enable the feature toggle only for your boss! {#step-4-enable-the-feature-toggle-only-for-your-boss}
 
-The next step is to change the activation strategy to only target your boss. You can use the “userWithId”-strategy for that. Using the configuration shown below will only enable the feature toggle for “boss@company.com” and “me@company.com”. Thus, you can safely test your feature in production, without exposing it to your users. In [control roll-out](./control_rollout) with strategies we will go in to greater details on how to use activation strategies to gradually expose new features to your users.
+The next step is to change the activation strategy to only target your boss. You can use the “userIDs”-strategy for that. Using the configuration shown below will only enable the feature toggle for “boss@company.com” and “me@company.com”. Thus, you can safely test your feature in production, without exposing it to your users.
 
 ![Create a feature toggle](/img/create_feature_toggle_userIds.png)
 

diff --git a/website/docs/user_guide/index.md b/website/docs/user_guide/index.md
@@ -1,35 +1,65 @@
 ---
 id: index
-title: Introduction
+title: About the docs
 slug: /
 sidebar_position: 1
 ---
 
-Welcome to the Unleash documentation. Our goal with our documentation is to guide you through the most essential concepts of Unleash.
+:::note
+The docs are currently undergoing some heavy restructuring and development 👷‍♀️👷🏽 If something is unclear, don't hesitate to [let us know on Slack](https://join.slack.com/t/unleash-community/shared_invite/enQtNjUxMjU2MDc0MTAxLTJjYmViYjkwYmE0ODVlNmY1YjcwZGRmZWU5MTU1YTQ1Nzg5ZWQ2YzBlY2U1MjlmZDg5ZDRmZTMzNmQ5YmEyOGE)!
+:::
 
-One of the most important aspects of the architecture to understand is that feature toggles _are evaluated in a client SDKs_ which runs as part of your application. This makes toggle evaluations super-fast (_we talk nano-seconds_), scalable and resilient against network disturbances. In order to achieve this Unleash compromises a small update-delay when you change your toggle configurations until it is fully propagated to your application (in terms of seconds and is configurable).
+Welcome to the Unleash documentation, your one-stop shop to everything Unleash. Whether you're just getting started or have been using Unleash for years, you should be able to find answers to all your questions here.
 
-If you want more details you can read about [our unique architecture](https://www.getunleash.io/blog/our-unique-architecture).
+## Getting help
 
-### Unleash Server {#unleash-server}
+Have questions that you can't find the answer to in these docs? You can always turn to [the Unleash Slack community](https://join.slack.com/t/unleash-community/shared_invite/enQtNjUxMjU2MDc0MTAxLTJjYmViYjkwYmE0ODVlNmY1YjcwZGRmZWU5MTU1YTQ1Nzg5ZWQ2YzBlY2U1MjlmZDg5ZDRmZTMzNmQ5YmEyOGE) and ask us questions directly (or just come and hang out 😄).
 
-Before you can connect your application to Unleash you need a Unleash server. You have a few options available:
+## Documentation structure
 
-1. **Unleash Open-source**
-   - [Docker](deploy/getting_started)
-   - [Helm Chart](https://github.com/unleash/helm-charts/)
-   - [Click-to-deploy on Heroku](https://www.heroku.com/deploy/?template=https://github.com/Unleash/unleash)
-2. **Unleash Enterprise**
-   - [Hosted Plans](https://www.getunleash.io/plans)
-   - [Self-hosted](https://www.getunleash.io/blog/self-host-your-feature-toggle-system)
+Our documentation is split into four parts, using the [Diataxis documentation framework](https://diataxis.fr/):
+- [tutorials and introductory material](#tutorials)
+- [how-to guides](#how-to-guides)
+- [reference documentation](#reference-documentation)
+- [topic guides](#topic-guides)
 
-### System Overview {#system-overview}
+### Tutorials and introductory material {#tutorials}
 
-![system_overview](/img/Unleash_architecture.svg 'System Overview')
+New to Unleash? Not sure where to get started? The tutorials guide you through your first steps with Unleash:
+- [Unleash introductory overview](unleash_overview.md)
+- [Important Unleash concepts](important-concepts.md)
+- [Quickstart guides](quickstart.md)
 
-- **Unleash API** - The service holding all feature toggles and their configurations. Configurations declare which activation strategies to use and which parameters they should get. [API documentation](/api)
-- **Unleash Admin UI** - The dashboard used to manage feature toggles, define new strategies, look at metrics, etc. [Create your first feature toggle](user_guide/create-feature-toggle.md)
-- **Unleash SDK** - Used by clients to check if a feature is enabled or disabled. The SDK also collects metrics and sends them to the Unleash API. [See all our SDKs](sdks/index.md)
-- **Unleash Proxy** - Sits between frontend/native applications and the Unleash API. Ensures high performance and that you don't expose the full feature toggle configuration to end-users. [Read more about Unleash Proxy](sdks/unleash-proxy.md)
+### How-to guides
 
-To be super fast (_we talk nano-seconds_), the [client SDK](sdks/index.md) caches all feature toggles and their current configuration in memory. The activation strategies are also implemented in the SDK. This makes it really fast to check if a toggle is on or off because it is just a simple function operating on local state, without the need to poll data from the database.
+Our how-to guides show you how to perform a number of common tasks that you'll want to do. Think of them as recipes. They are more advanced than the tutorials and assume you have some working knowledge of Unleash.
+
+The guides are organized into the following categories:
+- [API how-tos](/how-to/api)
+- [Feature toggles, strategies, context, and general how-tos](/how-to/misc)
+- [Users and permissions how-tos](/how-to/users-and-permissions)
+- [Single Sign-On (SSO) how-tos](/how-to/sso)
+
+### Reference documentation
+
+The reference docs contain technical reference for Unleash and the API. Go here to find out how Unleash works and what configuration options are available. They're like an Unleash encyclopedia and assume you have a grip on key Unleash concepts.
+
+The reference docs are organized into the following topics:
+- [Addons](/addons)
+- [API documentation](/api)
+- [Unleash Client SDKs](/sdks)
+- [Deployment and management of Unleash](/deploy)
+- [Integrations with other systems](/integrations)
+- [Unleash concepts](/reference/concepts)
+
+### Topic guides
+
+[The topic guides](/topics) discuss high-level concepts related to Unleash and provide extra background information and explanations around these concepts.
+
+## Other resources and communities
+
+💻 The core of Unleash is all open source and [hosted on GitHub](https://www.heroku.com/deploy/?template=https://github.com/Unleash/unleash "Unleash on GitHub").
+
+💬 If you've got questions or just wanna chat to the team and other Unleash users, come [join our Slack community](https://join.slack.com/t/unleash-community/shared_invite/enQtNjUxMjU2MDc0MTAxLTJjYmViYjkwYmE0ODVlNmY1YjcwZGRmZWU5MTU1YTQ1Nzg5ZWQ2YzBlY2U1MjlmZDg5ZDRmZTMzNmQ5YmEyOGE)
+
+🐦 You can also follow us [on Twitter](https://twitter.com/getunleash "Unleash on Twitter"), [LinkedIn](https://www.linkedin.com/company/getunleash/ "Unleash on LinkedIn"), or [Instagram](https://www.instagram.com/getunleash/ "Unleash on Instagram") for more updates and extra content.
diff --git a/website/docs/user_guide/token.md b/website/docs/user_guide/token.md
@@ -1,6 +1,6 @@
 ---
 id: api-token
-title: API Tokens
+title: How to create API Tokens
 ---
 
 In order to connect to Unleash clients will need an API token to grant access. A client SDK will need to token with "client privileges", which allows them to fetch feature toggle configuration and post usage metrics back.