Repository: RasaHQ/rasa
Pull request: Docs accessibility
**Proposed changes**:
- close https://github.com/RasaHQ/rasa/issues/6765

**Status (please check what you already did)**:
- [ ] added some tests for the functionality
- [x] updated the documentation
- [ ] updated the changelog (please check [changelog](https://github.com/RasaHQ/rasa/tree/master/changelog) for instructions)
- [ ] reformat files using `black` (please check [Readme](https://github.com/RasaHQ/rasa#code-style) for instructions)


Problem statement:
improve accessibility in docs
- [x] make sure that every image has a descriptive caption and descriptive alt text 
- [x] check for non-descriptive link texts, like `here` and `this page` and replace with the name of what is being linked to
- [ ] check for pages where lists/bullets are being used where headers would be more appropriate

Hints from issue discussion:

Commit message: update pages that shouldnt be all lists

Patch to review:
diff --git a/CHANGELOG.mdx b/CHANGELOG.mdx
index ee08f4481ade..d84ea06c0168 100644
--- a/CHANGELOG.mdx
+++ b/CHANGELOG.mdx
@@ -140,7 +140,7 @@ https://github.com/RasaHQ/rasa/tree/master/changelog/ . -->
 
 * [#5521](https://github.com/rasahq/rasa/issues/5521): Responses used in ResponseSelector now support new lines with explicitly adding `\\n` between them.
 
-* [#5758](https://github.com/rasahq/rasa/issues/5758): Fixed a bug in [rasa export](./command-line-interface.mdx#rasa-export)) which caused Rasa Open Source to only migrate conversation events from the last [Session configuration](./domain.mdx#session-configuration).
+* [#5758](https://github.com/rasahq/rasa/issues/5758): Fixed a bug in [`rasa export`](./command-line-interface.mdx#rasa-export)) which caused Rasa Open Source to only migrate conversation events from the last [Session configuration](./domain.mdx#session-configuration).
 
 ## [1.10.1] - 2020-05-15
 
@@ -336,8 +336,8 @@ https://github.com/RasaHQ/rasa/tree/master/changelog/ . -->
   connected to a PostgreSQL database.
 
   The schema is added to the connection string option's `-csearch_path` key, e.g.
-  `-options=-csearch_path=<SCHEMA_NAME>` (see
-  [https://www.postgresql.org/docs/11/contrib-dblink-connect.html](https://www.postgresql.org/docs/11/contrib-dblink-connect.html) for more details).
+  `-options=-csearch_path=<SCHEMA_NAME>` (see the
+  [PostgreSQL docs](https://www.postgresql.org/docs/11/contrib-dblink-connect.html) for more details).
   As before, if no `POSTGRESQL_SCHEMA` is defined, Rasa uses the database's default
   schema (`public`).
 
@@ -566,7 +566,7 @@ https://github.com/RasaHQ/rasa/tree/master/changelog/ . -->
 
 * [#5230](https://github.com/rasahq/rasa/issues/5230): Refactor how GPU and CPU environments are configured for TensorFlow 2.0.
 
-  Please refer to the [documentation](./tuning-your-model.mdx#configuring-tensorflow) to understand
+  Please refer to the documentation on [Configuring TensorFlow](./tuning-your-model.mdx#configuring-tensorflow) to understand
   which environment variables to set in what scenarios. A couple of examples are shown below as well:
 
   ```python
@@ -583,7 +583,7 @@ https://github.com/RasaHQ/rasa/tree/master/changelog/ . -->
 * [#5266](https://github.com/rasahq/rasa/issues/5266): Added a new NLU component [DIETClassifier](./components.mdx#dietclassifier) and a new policy [TEDPolicy](./policies.mdx#ted-policy).
 
   DIET (Dual Intent and Entity Transformer) is a multi-task architecture for intent classification and entity
-  recognition. You can read more about this component in our [documentation](./components.mdx#dietclassifier).
+  recognition. You can read more about this component in the [DIETClassifier](./components.mdx#dietclassifier) documentation.
   The new component will replace the `EmbeddingIntentClassifier` and the
   [CRFEntityExtractor](./components.mdx#crfentityextractor) in the future.
   Those two components are deprecated from now on.
@@ -965,7 +965,7 @@ https://github.com/RasaHQ/rasa/tree/master/changelog/ . -->
 * [#4925](https://github.com/rasahq/rasa/issues/4925): “rasa init” will ask if user wants to train a model
 
 * [#4942](https://github.com/rasahq/rasa/issues/4942): Pin `multidict` dependency to 4.6.1 to prevent sanic from breaking,
-  see [https://github.com/huge-success/sanic/issues/1729](https://github.com/huge-success/sanic/issues/1729)
+  see [the Sanic GitHub issue](https://github.com/huge-success/sanic/issues/1729) for more info.
 
 * [#4985](https://github.com/rasahq/rasa/issues/4985): Fix errors during training and testing of `ResponseSelector`.
 
@@ -980,7 +980,7 @@ https://github.com/RasaHQ/rasa/tree/master/changelog/ . -->
 * [#4914](https://github.com/rasahq/rasa/issues/4914): Added `rasa/nlu/schemas/config.yml` to wheel package
 
 * [#4942](https://github.com/rasahq/rasa/issues/4942): Pin `multidict` dependency to 4.6.1 to prevent sanic from breaking,
-  see [https://github.com/huge-success/sanic/issues/1729](https://github.com/huge-success/sanic/issues/1729)
+  see [the Sanic GitHub issue](https://github.com/huge-success/sanic/issues/1729)
 
 ## [1.5.2] - 2019-12-09
 
@@ -1310,7 +1310,7 @@ Regression: changes from `1.2.12` were missing from `1.4.0`, readded them
 ### Bugfixes
 
 * Added the ability to properly deal with spaCy `Doc`-objects created on
-  empty strings as discussed [here](https://github.com/RasaHQ/rasa/issues/4445).
+  empty strings as discussed in [issue #4445](https://github.com/RasaHQ/rasa/issues/4445).
   Only training samples that actually bear content are sent to `self.nlp.pipe`
   for every given attribute. Non-content-bearing samples are converted to empty
   `Doc`-objects. The resulting lists are merged with their preserved order and
diff --git a/docs/docs/architecture.mdx b/docs/docs/architecture.mdx
index 0bcf17175a6f..d83c85a3bf3d 100644
--- a/docs/docs/architecture.mdx
+++ b/docs/docs/architecture.mdx
@@ -13,7 +13,8 @@ responds to a message:
 
 
 
-<img alt="image" src={useBaseUrl("/img/rasa-message-processing.png")} />
+<img caption="Rasa Open Source architecture" src={useBaseUrl("/img/rasa-message-processing.png")}
+alt="A visual representation of the steps that follow."/>
 
 The steps are:
 
@@ -21,19 +22,13 @@ The steps are:
    converts it into a dictionary including the original text, the intent,
    and any entities that were found. This part is handled by NLU.
 
-2. The `Tracker` is the object which keeps track of conversation state.
-   It receives the info that a new message has come in.
+2. The message is passed from the `Interpreter` to the `Tracker`.
+   The `Tracker` is the object which keeps track of conversation state.
 
-3. The policy receives the current state of the tracker.
+3. The current state of the tracker is sent to each policy.
 
-4. The policy chooses which action to take next.
+4. Each policy chooses which action to take next.
 
 5. The chosen action is logged by the tracker.
 
 6. A response is sent to the user.
-
-:::note
-Messages can be text typed by a human, or structured input
-like a button press.
-
-:::
diff --git a/docs/docs/business-logic.mdx b/docs/docs/business-logic.mdx
index 56aaf77bd1bc..e75229be8d9b 100644
--- a/docs/docs/business-logic.mdx
+++ b/docs/docs/business-logic.mdx
@@ -9,7 +9,7 @@ Conversational assistants often support user goals that involve collecting requi
 from the user before doing something for them. For example, a restaurant search bot would need to gather a few pieces of information
 about the user's preferences to find them a suitable restaurant:
 
-<Chat caption="Find a restaurant">
+<Chat caption="Finding a restaurant">
 <ChatUserText>Help me find a restaurant</ChatUserText>
 <ChatBotText>What cuisine?</ChatBotText>
 <ChatUserText>I'm looking for Tuscan food</ChatUserText>
diff --git a/docs/docs/components.mdx b/docs/docs/components.mdx
index cb476ac46c70..f4c5dcd597a9 100644
--- a/docs/docs/components.mdx
+++ b/docs/docs/components.mdx
@@ -71,8 +71,8 @@ word vectors in your pipeline.
      [configuration](./model-configuration.mdx) file.
 
   For a full example of how to train MITIE word vectors, check out
-  [this blogpost](http://www.crownpku.com/2017/07/27/%E7%94%A8Rasa_NLU%E6%9E%84%E5%BB%BA%E8%87%AA%E5%B7%B1%E7%9A%84%E4%B8%AD%E6%96%87NLU%E7%B3%BB%E7%BB%9F.html)
-  of creating a MITIE model from a Chinese Wikipedia dump.
+  [用Rasa NLU构建自己的中文NLU系统](http://www.crownpku.com/2017/07/27/%E7%94%A8Rasa_NLU%E6%9E%84%E5%BB%BA%E8%87%AA%E5%B7%B1%E7%9A%84%E4%B8%AD%E6%96%87NLU%E7%B3%BB%E7%BB%9F.html),
+  a blogpost that goes through creating a MITIE model from a Chinese Wikipedia dump.
 
 
 
@@ -178,8 +178,8 @@ word vectors in your pipeline.
   available language models.
   Additionally, you can also specify the architecture variation of the chosen language model by specifying the
   parameter `model_weights`.
-  The full list of supported architectures can be found
-  [here](https://huggingface.co/transformers/pretrained_models.html).
+  The full list of supported architectures can be found in the
+  [HuggingFace documentation](https://huggingface.co/transformers/pretrained_models.html).
   If left empty, it uses the default model architecture that original Transformers library loads (see table below).
 
   ```
@@ -1297,9 +1297,9 @@ Intent classifiers assign one of the intents defined in the domain file to incom
   single semantic vector space. We use the dot-product loss to maximize the similarity with the target label and
   minimize similarities with negative samples.
 
-  If you want to learn more about the model, please take a look at our
-  [videos](https://www.youtube.com/playlist?list=PL75e0qA87dlG-za8eLI6t0_Pbxafk-cxb) where we explain the model
-  architecture in detail.
+  If you want to learn more about the model, check out the
+  [Algorithm Whiteboard](https://www.youtube.com/playlist?list=PL75e0qA87dlG-za8eLI6t0_Pbxafk-cxb) series on YouTube,
+  where we explain the model architecture in detail.
 
   :::note
   If during prediction time a message contains **only** words unseen during training
@@ -1912,7 +1912,9 @@ The `SpacyEntityExtractor` extractor does not provide a `confidence` level and w
   The extractor will always return 1.0 as a confidence, as it is a rule
   based system.
 
-  The list of supported languages can be found [here](https://github.com/facebook/duckling/tree/master/Duckling/Dimensions).
+  The list of supported languages can be found in the
+  [GitHub repo](https://github.com/facebook/duckling/tree/master/Duckling/Dimensions)
+  for Duckling.
 
 
 
@@ -2133,9 +2135,9 @@ The `SpacyEntityExtractor` extractor does not provide a `confidence` level and w
     single semantic vector space. We use the dot-product loss to maximize the similarity with the target label and
     minimize similarities with negative samples.
 
-    If you want to learn more about the model, please take a look at our
-    [videos](https://www.youtube.com/playlist?list=PL75e0qA87dlG-za8eLI6t0_Pbxafk-cxb) where we explain the model
-    architecture in detail.
+    If you want to learn more about the model, check out the
+    [Algorithm Whiteboard](https://www.youtube.com/playlist?list=PL75e0qA87dlG-za8eLI6t0_Pbxafk-cxb) series on YouTube,
+    where we explain the model architecture in detail.
 
     :::note
     If during prediction time a message contains **only** words unseen during training
@@ -2536,9 +2538,11 @@ Selectors predict a bot response from a set of candidate responses.
   template which has a text attribute for training. If none are found, it falls back to using the retrieval intent
   combined with the response key as the label.
 
-  See this [example assistant](https://github.com/RasaHQ/rasa/tree/master/examples/responseselectorbot) to understand
+  :::note examples and tutorials
+  Check out the [responseselectorbot](https://github.com/RasaHQ/rasa/tree/master/examples/responseselectorbot) for an example of
   how you can use the `ResponseSelector` component in your assistant. Additionally, you will find this tutorial on
   [handling FAQs](./chitchat-faqs.mdx) using a `ResponseSelector` useful as well.
+  :::
 
 
 The above configuration parameters are the ones you should configure to fit your model to your data.
@@ -2688,7 +2692,7 @@ You can create a custom component to perform a specific task which NLU doesn't c
 Below is the specification of the `rasa.nlu.components.Component`] class with the methods you'll need to implement.
 
 :::tip follow the tutorial
-There is a detailed tutorial on building custom components [here](https://blog.rasa.com/enhancing-rasa-nlu-with-custom-components/).
+There is a detailed tutorial on building custom components on the [Rasa Blog](https://blog.rasa.com/enhancing-rasa-nlu-with-custom-components/).
 
 :::
 
diff --git a/docs/docs/connectors/cisco-webex-teams.mdx b/docs/docs/connectors/cisco-webex-teams.mdx
index 10bdf2873a29..9684cf06bc00 100644
--- a/docs/docs/connectors/cisco-webex-teams.mdx
+++ b/docs/docs/connectors/cisco-webex-teams.mdx
@@ -12,8 +12,8 @@ Once you have them you can add these to your `credentials.yml`.
 
 **How to get the Cisco Webex Teams credentials:**
 
-You need to set up a bot. Check out the Cisco Webex for Developers
-[documentation](https://developer.webex.com/docs/bots) for information
+You need to set up a bot. Check out the [Cisco Webex for Developers
+documentation](https://developer.webex.com/docs/bots) for information
 about how to create your bot.
 
 After you have created the bot through Cisco Webex Teams, you need to create a
diff --git a/docs/docs/connectors/hangouts.mdx b/docs/docs/connectors/hangouts.mdx
index 774699e14b83..239d1e53b77a 100644
--- a/docs/docs/connectors/hangouts.mdx
+++ b/docs/docs/connectors/hangouts.mdx
@@ -16,7 +16,7 @@ Google Developer Console that includes the Hangouts API. There you can specify y
 and also obtain your project id, which determines the scope for the OAuth2 authorization in case you
 want to use OAuth2. The Hangouts Chat API sends a Bearer token with every request, but it is up to
 the bot to actually verify the token, hence the channel also works without this.
-For more information see the official Google resources [https://developers.google.com/hangouts/chat](https://developers.google.com/hangouts/chat).
+For more information see the [Google Hangouts documentation](https://developers.google.com/hangouts/chat).
 
 The possibility to implement asynchronous communication between Hangouts Chat and bot exists, but due
 to the usually synchronous nature of Rasa bots, this functionality is not included in this channel.
diff --git a/docs/docs/connectors/slack.mdx b/docs/docs/connectors/slack.mdx
index e400c9a9b210..f6668ff3af00 100644
--- a/docs/docs/connectors/slack.mdx
+++ b/docs/docs/connectors/slack.mdx
@@ -12,7 +12,7 @@ Once you have them you can add these to your `credentials.yml`.
 
 **How to get the Slack credentials:** You need to set up a Slack app.
 
-1. To create the app go to [https://api.slack.com/apps](https://api.slack.com/apps) and click
+1. To create the app go to [Your Apps](https://api.slack.com/apps) and click
    on **Create New App**.
 
 2. Activate the following features:
@@ -74,7 +74,7 @@ slack:
   proxy: "http://myProxy.online"  # Proxy Server to route your traffic through. This configuration is optional.
   slack_retry_reason_header: "x-slack-retry-reason"  # Slack HTTP header name indicating reason that slack send retry request. This configuration is optional.
   slack_retry_number_header: "x-slack-retry-num"  # Slack HTTP header name indicating the attempt number. This configuration is optional.
-  errors_ignore_retry: None  # Any error codes given by Slack included in this list will be ignored. Error codes are listed [here](https://api.slack.com/events-api#errors).
+  errors_ignore_retry: None  # Any error codes given by Slack included in this list will be ignored. Error codes are listed in the [Slack API Reference](https://api.slack.com/events-api#errors).
   use_threads: False  # If set to True, bot responses will appear as a threaded message in Slack. This configuration is optional and set to False by default.
 ```
 
diff --git a/docs/docs/contextual-conversations.mdx b/docs/docs/contextual-conversations.mdx
index 0538fdb491db..27f011427f85 100644
--- a/docs/docs/contextual-conversations.mdx
+++ b/docs/docs/contextual-conversations.mdx
@@ -18,8 +18,7 @@ For example, if a user asks Sara, the Rasa bot, how to get started using Rasa,
 Sara gives the user
 different information based on whether they've built an AI assistant before or not:
 
-A conversation with a new user:
-<Chat caption="New User Conversation">
+<Chat caption="A conversation with a new user">
 <ChatUserText>How can I get started with Rasa?</ChatUserText>
 <ChatBotText>To determine how I can help you best, I'm going to ask you a few questions.</ChatBotText>
 <ChatBotText>Let's go. Are you new to Rasa?</ChatBotText>
@@ -27,8 +26,7 @@ A conversation with a new user:
 <ChatBotText>And have you built a contextual assistant or a bot before?</ChatBotText>
 </Chat>
 
-A conversation with a returning user:
-<Chat caption="Returning User Conversation">
+<Chat caption="A conversation with a returning user">
 <ChatUserText>How can I get started with Rasa?</ChatUserText>
 <ChatBotText>To determine how I can help you best, I'm going to ask you a few questions.</ChatBotText>
 <ChatBotText>Let's go. Are you new to Rasa?</ChatBotText>
@@ -99,8 +97,8 @@ In addition to adding stories to account for context,
 machine learning policies can help your model generalize
 to unseen conversation paths. **It is important
 to understand that using machine-learning policies does not mean letting go of control over your
-assistant.** If a rule based policy is able to make a prediction, that prediction will
-always have a higher priority (read more [here](./policies.mdx#action-selection)) and predict the next action.
+assistant.** If a rule-based policy is able to make a prediction, that prediction will
+always have a higher [priority](./policies.mdx#policy-priority) and will predict the next action.
 
 The [TEDPolicy](https://blog.rasa.com/unpacking-the-ted-policy-in-rasa-open-source/) is made to handle
 unexpected user behaviors. For example,
diff --git a/docs/docs/conversation-driven-development.mdx b/docs/docs/conversation-driven-development.mdx
index f6508a08d25e..cba88a9e7df9 100644
--- a/docs/docs/conversation-driven-development.mdx
+++ b/docs/docs/conversation-driven-development.mdx
@@ -7,7 +7,7 @@ description: Find out about best practices for conversational AI using Conversat
 
 ## What is CDD?
 
-Conversation-Driven Development (CDD) is the process of listening to your users and using those insights to improve your AI assistant. It is the overarching best practice approach for chatbot development. 
+Conversation-Driven Development (CDD) is the process of listening to your users and using those insights to improve your AI assistant. It is the overarching best practice approach for chatbot development.
 
 Developing great AI assistants is challenging because users will always say something you didn't anticipate. The principle behind CDD is that in every conversation users are telling you—in their own words—exactly what they want. By practicing CDD at every stage of bot development, you orient your assistant towards real user language and behavior.
 
@@ -22,18 +22,18 @@ CDD includes the following actions:
 
 CDD is not a linear process; you'll circle back to the same actions over and over as you develop and improve your bot.
 
-Read more about these actions and the concept of CDD [here](https://blog.rasa.com/conversation-driven-development-a-better-approach-to-building-ai-assistants/). 
+Read more about these actions and the concept of CDD on the [Rasa Blog](https://blog.rasa.com/conversation-driven-development-a-better-approach-to-building-ai-assistants/).
 
-You can also check out [Rasa X](https://rasa.com/docs/rasa-x/), a purpose-built tool for CDD. 
+You can also check out [Rasa X](https://rasa.com/docs/rasa-x/), a purpose-built tool for CDD.
 
 ## CDD in early stages of development
 
 If you're at the earliest stage of bot development, it might seem like CDD has no role to play - after all, you have no conversations yet! However, there are CDD actions you can take at the very beginning of bot development:
 
 1. See the best practices for [NLU data](generating-nlu-data.mdx) and [Stories](writing-stories.mdx) for details on creating training data with CDD in mind.
-2. Give your bot to test users early on. 
+2. Give your bot to test users early on.
 
-    CDD is all about listening to your users, so the earlier you find some, the better. 
+    CDD is all about listening to your users, so the earlier you find some, the better.
 
     Test users can be anyone who doesn't already know how your bot works from the inside. People on the bot development team should not be test users, since they know exactly what the bot can and can't do. Don't overinstruct your test users; they should have only as much knowledge of the bot's domain as your end users will have.
 
@@ -45,27 +45,37 @@ If you're at the earliest stage of bot development, it might seem like CDD has n
 At this stage, you can [install Rasa X in local mode](https://rasa.com/docs/rasa-x/installation-and-setup/installation-guide/#local-mode) to make it easier to share your bot with test users, collect conversations, and apply NLU and Story best practices based on the conversations you collect.
 
 
-## CDD with a bot in production 
+## CDD with a bot in production
 
-Once your bot is in production, you'll have more conversations to gain insights from. Then you can fully apply CDD actions. 
-At this stage, you can [install Rasa X on a server](https://rasa.com/docs/rasa-x/installation-and-setup/installation-guide/#helm-chart) 
+Once your bot is in production, you'll have more conversations to gain insights from. Then you can fully apply CDD actions.
+At this stage, you can [install Rasa X on a server](https://rasa.com/docs/rasa-x/installation-and-setup/installation-guide/#helm-chart)
 to both deploy your bot and enable CDD with a bot in production.
 
-*   **Review**: Look in conversations for what users are really asking for.
+### Review
 
-    Your test users had at least some instruction about what the bot was intended to do; real users often either have no idea, or ignore instructions given to them. You can't cater to every unexpected user behavior, but you can try to address the main friction points you notice. Here are some things you could consider looking for:
+Look in conversations for what users are really asking for.
 
-    *   Look at conversations where an “out_of_scope” intent or fallback behavior occurred. These could indicate a potential new skill, or just a misclassified user utterance.
-    *   Look for user frustration, such as requests for transfer to a human.
+Your test users had at least some instruction about what the bot was intended to do; real users often either have no idea, or ignore instructions given to them. You can't cater to every unexpected user behavior, but you can try to address the main friction points you notice. Here are some things you could consider looking for:
 
-*   **Annotate**: Continue to follow [best practices for NLU](generating-nlu-data.mdx) as you add new user utterances from real conversations to your training data. Be careful not to overfit your NLU model to utterances like those already in your training data. This can happen when you continuously add user utterances that were already predicted correctly and with high confidence to your training data.  To avoid overfitting and help your model generalize to more diverse user utterances, add only user utterances that the model previously predicted incorrectly or with low confidence. 
+*   Look at conversations where an “out_of_scope” intent or fallback behavior occurred. These could indicate a potential new skill, or just a misclassified user utterance.
+*   Look for user frustration, such as requests for transfer to a human.
 
-*   **Test:** Add successful user conversations to your [test conversations](testing-your-assistant.mdx). Doing this consistently will help ensure you don't introduce regressions as you make other fixes to your bot. 
+### Annotate
 
-*   **Track:** Look for clues to success and failure to help you track your bot's performance.
+Continue to follow [best practices for NLU](generating-nlu-data.mdx) as you add new user utterances from real conversations to your training data. Be careful not to overfit your NLU model to utterances like those already in your training data. This can happen when you continuously add user utterances that were already predicted correctly and with high confidence to your training data.  To avoid overfitting and help your model generalize to more diverse user utterances, add only user utterances that the model previously predicted incorrectly or with low confidence.
 
-    Some metrics are external to your bot. For example, if you are building a bot to relieve demand on a customer service call center, one metric for success could be the reduction in traffic to the call center. Others you can get directly from conversations, such as whether a user reaches a certain action that represents achieving the user goal.
+### Test
 
-    Automatically tracked metrics are by nature proxy metrics; the only way to get a true measure of success would be to individually review and rate every single conversation with your bot. While this clearly isn't realistic, just keep in mind that no metric is a perfect representation of your bot's performance, so don't really only on metrics to see where your bot needs improvement.
+Add successful user conversations to your [test conversations](testing-your-assistant.mdx). Doing this consistently will help ensure you don't introduce regressions as you make other fixes to your bot.
 
-*   **Fix:** Continue to follow [best practices for Stories](writing-stories.mdx) as you expand and improve your bot's skills. Let user demand guide which skills you add and which fixes you make. Make smaller changes frequently rather than making big changes only once in a while. This will help you gauge the effectiveness of changes you're making, since you'll get user feedback more frequently. Your [CI/CD pipeline ](setting-up-ci-cd.mdx) should allow you to do so with confidence.
+### Track
+
+Look for clues to success and failure to help you track your bot's performance.
+
+Some metrics are external to your bot. For example, if you are building a bot to relieve demand on a customer service call center, one metric for success could be the reduction in traffic to the call center. Others you can get directly from conversations, such as whether a user reaches a certain action that represents achieving the user goal.
+
+Automatically tracked metrics are by nature proxy metrics; the only way to get a true measure of success would be to individually review and rate every single conversation with your bot. While this clearly isn't realistic, just keep in mind that no metric is a perfect representation of your bot's performance, so don't really only on metrics to see where your bot needs improvement.
+
+### Fix
+
+Continue to follow [best practices for Stories](writing-stories.mdx) as you expand and improve your bot's skills. Let user demand guide which skills you add and which fixes you make. Make smaller changes frequently rather than making big changes only once in a while. This will help you gauge the effectiveness of changes you're making, since you'll get user feedback more frequently. Your [CI/CD pipeline ](setting-up-ci-cd.mdx) should allow you to do so with confidence.
diff --git a/docs/docs/fallback-handoff.mdx b/docs/docs/fallback-handoff.mdx
index 94b6a9a1f86c..0d38e9e72672 100644
--- a/docs/docs/fallback-handoff.mdx
+++ b/docs/docs/fallback-handoff.mdx
@@ -31,7 +31,7 @@ nlu:
 ```
 
 As with every intent, you should source the majority of your examples
-[from real conversations](conversation-driven-development.mdx). 
+[from real conversations](conversation-driven-development.mdx).
 
 
 ### 2. Defining the response message
@@ -142,7 +142,7 @@ the corresponding confidence threshold using the following steps:
 
 #### 1. Updating the configuration
 
-You will need to add the RulePolicy to your policies in config.yml. 
+You will need to add the RulePolicy to your policies in config.yml.
 By default, the rule policy comes with the settings below:
 
 ```yaml-rasa
@@ -161,7 +161,7 @@ policies:
 #### 2. Defining the default response message
 
 To define what your bot will say when action confidence is below the threshold,
-define a response `utter_default`. 
+define a response `utter_default`.
 
 ```yaml-rasa
 responses:
@@ -275,7 +275,7 @@ responses:
 
 Rasa provides default implementations for asking which intent the user
 meant and for asking the user to rephrase. To customize the behavior of these actions,
-see the [documentation default actions](default-actions.mdx).
+see the documentation on[default actions](default-actions.mdx).
 
 #### 3. Defining a Two-Stage Fallback rule
 
@@ -320,7 +320,7 @@ starterpacks.
 ## Summary
 
 To let your assistant gracefully handle failures, you should handle known
-out-of-scope messages and add a form of fallback behavior. If you want to add human 
+out-of-scope messages and add a form of fallback behavior. If you want to add human
 handoff, you can add it in addition or as a final step in your fallback
 set up.
 Here's a summary of changes you need to make for each method:
diff --git a/docs/docs/glossary.mdx b/docs/docs/glossary.mdx
index 51ce778bbbee..3dfd66de2bf4 100644
--- a/docs/docs/glossary.mdx
+++ b/docs/docs/glossary.mdx
@@ -51,7 +51,7 @@ description: Glossary for all Rasa-related terms
 
 ## [Event](https://rasa.com/docs/action-server/events)
 
-  All conversations in Rasa are represented as a sequence of events. For instance, a `UserUttered` represents a user entering a message, and an `ActionExecuted` represents the assistant executing an action. You can learn more about them [here](https://rasa.com/docs/action-server/events).
+  All conversations in Rasa are represented as a sequence of events. For instance, a `UserUttered` represents a user entering a message, and an `ActionExecuted` represents the assistant executing an action.
 
 ## FAQs
 
diff --git a/docs/docs/how-to-deploy.mdx b/docs/docs/how-to-deploy.mdx
index 47f95e2ff3d5..95a2c40d5bf8 100644
--- a/docs/docs/how-to-deploy.mdx
+++ b/docs/docs/how-to-deploy.mdx
@@ -95,7 +95,8 @@ The following steps assume that you already created a GitHub repository and you
 To create a workflow for building and pushing a Docker image into a DockerHub registry:
 
 1. Add GitHub Secrets with your DockerHub login name and password.
-   [Here](https://docs.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets#creating-encrypted-secrets-for-a-repository) you can find details on how to create encrypted secrets for a repository.
+   You can find details on how to create encrypted secrets for a repository
+   in the [Github docs](https://docs.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets#creating-encrypted-secrets-for-a-repository)
 
    The example uses the following secrets:
    - `DOCKER_HUB_LOGIN` - a login name for DockerHub
diff --git a/docs/docs/migrate-from/google-dialogflow-to-rasa.mdx b/docs/docs/migrate-from/google-dialogflow-to-rasa.mdx
index b9fbbfde42c0..d50f31f9f11e 100644
--- a/docs/docs/migrate-from/google-dialogflow-to-rasa.mdx
+++ b/docs/docs/migrate-from/google-dialogflow-to-rasa.mdx
@@ -15,13 +15,16 @@ Navigate to your agent's settings by clicking the gear icon.
 
 
 
-<img alt="Dialogflow Export" src={useBaseUrl("/img/dialogflow_export.png")} width="240" />
+<img caption="Selecting settings" src={useBaseUrl("/img/dialogflow_export.png")} width="240"
+alt="In DialogFlow, the gear icon that indicates settings sits next to the dropdown menu for
+choosing between projects."/>
 
 Click on the 'Export and Import' tab and click on the 'Export as ZIP' button.
 
 
 
-<img alt="Dialogflow Export 2" src={useBaseUrl("/img/dialogflow_export_2.png")} width="675" />
+<img caption="Selecting Export and Import" src={useBaseUrl("/img/dialogflow_export_2.png")} width="675"
+alt="The Settings page will let you select from multiple headers, of which you want to select Export and Import."/>
 
 This will download a file with a `.zip` extension. Unzip this file to create a folder.
 
diff --git a/docs/docs/migrate-from/microsoft-luis-to-rasa.mdx b/docs/docs/migrate-from/microsoft-luis-to-rasa.mdx
index 6af8577fa801..2d626f8b22cb 100644
--- a/docs/docs/migrate-from/microsoft-luis-to-rasa.mdx
+++ b/docs/docs/migrate-from/microsoft-luis-to-rasa.mdx
@@ -15,7 +15,9 @@ on the three dots menu next to the app you want to export.
 
 
 
-<img alt="LUIS Export" src={useBaseUrl("/img/luis_export.png")} width="240" />
+<img caption="Selecting Export a" src={useBaseUrl("/img/luis_export.png")}
+alt="Opening the menu in the top right corner of LUIS Applications reveals
+the Export app option." width="240" />
 
 Select 'Export App'. This will download a file with a `.json` extension that can be imported directly into Rasa.
 
diff --git a/docs/docs/model-configuration.mdx b/docs/docs/model-configuration.mdx
index adb797b5f75a..94b97fe21dc2 100644
--- a/docs/docs/model-configuration.mdx
+++ b/docs/docs/model-configuration.mdx
@@ -7,23 +7,21 @@ description: Learn about model configuration for Rasa Open Source.
 import useBaseUrl from '@docusaurus/useBaseUrl';
 
 The configuration file defines the NLU and Core components that your model will use. The
-`language` and `pipeline` keys specify how the NLU model should be built. You can
-learn about choosing components for your NLU pipeline [here](./tuning-your-model.mdx). The
+`language` and `pipeline` keys specify the [components](./components.mdx) that make up the NLU model. The
 `policies` key defines the [policies](./policies.mdx) that the Core model will
 use.
 
-## Suggested Config
+If you don't know which components or policies to choose, you can use the
+the Suggested Config feature, which will recommend sensible defaults.
 
-You always need to specify the `language` key in your `config.yml` file with the
-2-letter ISO language code.
+## Suggested Config
 
-The two other keys (`pipeline` and `policies`) can be left out or left empty. When
-running `rasa train`, the Suggested Config feature will select a default configuration
-for the missing key(s) which will then be used to train the model.
+You can leave the `pipeline` and/or `policies` key out of your configuration file.
+When you run `rasa train`, the Suggested Config feature will select a default configuration
+for the missing key(s) to train the model.
 
-Please note, that only the default configuration for `pipeline` will be automatically selected
-if you run `rasa train nlu`, and only the default configuration for `policies`
-will be selected if you run `rasa train core`.
+Make sure to specify the `language` key in your `config.yml` file with the
+2-letter ISO language code.
 
 Example `config.yml` file:
 
@@ -43,3 +41,10 @@ key when training again.
 As long as you leave the configuration commented out and don't specify any configuration
 for a key yourself, a default configuration will be suggested whenever you train a new
 model.
+
+:::note nlu- or core- only models
+
+Only the default configuration for `pipeline` will be automatically selected
+if you run `rasa train nlu`, and only the default configuration for `policies`
+will be selected if you run `rasa train core`.
+:::
diff --git a/docs/docs/nlu-training-data.mdx b/docs/docs/nlu-training-data.mdx
index 183ef6f726ae..9c60f8b74d8d 100644
--- a/docs/docs/nlu-training-data.mdx
+++ b/docs/docs/nlu-training-data.mdx
@@ -57,7 +57,7 @@ Regular expressions can be used in two different ways:
 
 For example, if your entity has a deterministic structure (like a zipcode or an email address), you can use a regular
 expression to ease detection of that entity (using the [RegexFeaturizer](./components.mdx#regexfeaturizer)) or to directly extract the entities from
-the user message (using the [RegexEntityExtractor](./components.mdx#regexentityextractor)). 
+the user message (using the [RegexEntityExtractor](./components.mdx#regexentityextractor)).
 
 
 In case you are using the regular expressions for the [RegexFeaturizer](./components.mdx#regexfeaturizer) the name of the regular expression does
@@ -94,7 +94,7 @@ training data!
 This feature is experimental.
 We introduce experimental features to get feedback from our community, so we encourage you to try it out!
 However, the functionality might be changed or removed in the future.
-If you have feedback (positive or negative) please share it with us on the [forum](https://forum.rasa.com).
+If you have feedback (positive or negative) please share it with us on the [Rasa Forum](https://forum.rasa.com).
 
 :::
 
diff --git a/docs/docs/reaching-out-to-user.mdx b/docs/docs/reaching-out-to-user.mdx
index 2866118e0b4a..b5e03e29bd04 100644
--- a/docs/docs/reaching-out-to-user.mdx
+++ b/docs/docs/reaching-out-to-user.mdx
@@ -170,7 +170,7 @@ curl -H "Content-Type: application/json" -X POST -d \
 ```
 
 You should see the bot respond in your channel:
-<Chat caption="Bot response">
+<Chat caption="A reminder">
 <ChatBotText>Your Orchid needs some water!</ChatBotText>
 </Chat>
 
diff --git a/docs/docs/setting-up-ci-cd.mdx b/docs/docs/setting-up-ci-cd.mdx
index 0d239b86a7ed..8f8b9f8ae602 100644
--- a/docs/docs/setting-up-ci-cd.mdx
+++ b/docs/docs/setting-up-ci-cd.mdx
@@ -131,7 +131,7 @@ opposed to using a static NLU test set, which can easily become outdated.
 
 Because this test doesn't result in a pass/fail exit code, it's best to make
 the results visible so that you can interpret them.
-For example, [this workflow](https://gist.github.com/amn41/de555c93913a01fbd56df2e2d211862c)
+For example, [this GitHub Actions Workflow](https://gist.github.com/amn41/de555c93913a01fbd56df2e2d211862c)
 includes commenting on a PR with a results table that shows which intents are confused with others.
 
 Since NLU comparison can be a fairly resource intensive test, you may choose to run this test
diff --git a/docs/docs/stories.mdx b/docs/docs/stories.mdx
index 7c0ff921ee5e..5387bc170a78 100644
--- a/docs/docs/stories.mdx
+++ b/docs/docs/stories.mdx
@@ -62,8 +62,8 @@ that your assistant's dialogue management model doesn't know which events a cust
 action will return.
 
 Because of this, events such as setting a slot or activating/deactivating a form have to be
-explicitly written out as part of the stories. You can read more about
-the different types of events [here](https://rasa.com/docs/action-server/events).
+explicitly written out as part of the stories. For more info, see the documentation on
+[Events](https://rasa.com/docs/action-server/events).
 
 #### Slot Events
 
diff --git a/docs/docs/tracker-stores.mdx b/docs/docs/tracker-stores.mdx
index 3effd33763a8..2322fe8933ce 100644
--- a/docs/docs/tracker-stores.mdx
+++ b/docs/docs/tracker-stores.mdx
@@ -11,403 +11,375 @@ abstract: Your assistant's conversations are stored within a tracker store.
 
 ## InMemoryTrackerStore (default)
 
+`InMemoryTrackerStore` is the default tracker store. It is used if no other
+tracker store is configured. It stores the conversation history in memory.
 
-* **Description**
+:::note
+As this store keeps all history in memory, the entire history is lost if you restart the Rasa server.
 
-  `InMemoryTrackerStore` is the default tracker store. It is used if no other
-  tracker store is configured. It stores the conversation history in memory.
+:::
 
-  :::note
-  As this store keeps all history in memory, the entire history is lost if you restart the Rasa server.
 
-  :::
 
+### **Configuration**
 
-
-* **Configuration**
-
-  To use the `InMemoryTrackerStore` no configuration is needed.
+No configuration is needed to use the `InMemoryTrackerStore`.
 
 
 ## SQLTrackerStore
 
+You can use an `SQLTrackerStore` to store your assistant's conversation history in an SQL database.
 
-* **Description**
-
-  `SQLTrackerStore` can be used to store the conversation history in an SQL database.
-  Storing your trackers this way allows you to query the event database by sender_id, timestamp, action name,
-  intent name and typename.
-
-
-
-* **Configuration**
+### Configuration
 
-  To set up Rasa Open Source with SQL the following steps are required:
+To set up Rasa Open Source with SQL the following steps are required:
 
-  1. Add required configuration to your `endpoints.yml`:
+1. Add required configuration to your `endpoints.yml`:
 
-     ```yaml-rasa title="endpoints.yml"
-     tracker_store:
-         type: SQL
-         dialect: "postgresql"  # the dialect used to interact with the db
-         url: ""  # (optional) host of the sql db, e.g. "localhost"
-         db: "rasa"  # path to your db
-         username:  # username used for authentication
-         password:  # password used for authentication
-         query: # optional dictionary to be added as a query string to the connection URL
-           driver: my-driver
-     ```
+ ```yaml-rasa title="endpoints.yml"
+ tracker_store:
+     type: SQL
+     dialect: "postgresql"  # the dialect used to interact with the db
+     url: ""  # (optional) host of the sql db, e.g. "localhost"
+     db: "rasa"  # path to your db
+     username:  # username used for authentication
+     password:  # password used for authentication
+     query: # optional dictionary to be added as a query string to the connection URL
+       driver: my-driver
+ ```
 
-  2. To start the Rasa server using your SQL backend,
-     add the `--endpoints` flag, e.g.:
+2. To start the Rasa server using your SQL backend,
+ add the `--endpoints` flag, e.g.:
 
-     ```bash
-     rasa run -m models --endpoints endpoints.yml
-     ```
+ ```bash
+ rasa run -m models --endpoints endpoints.yml
+ ```
 
-  3. If deploying your model in Docker Compose, add the service to your `docker-compose.yml`:
+3. If deploying your model in Docker Compose, add the service to your `docker-compose.yml`:
 
-     ```yaml-rasa title="docker-compose.yml"
-     postgres:
-       image: postgres:latest
-     ```
+ ```yaml-rasa title="docker-compose.yml"
+ postgres:
+   image: postgres:latest
+ ```
 
-     To route requests to the new service, make sure that the `url` in your `endpoints.yml`
-     references the service name:
+ To route requests to the new service, make sure that the `url` in your `endpoints.yml`
+ references the service name:
 
-     ```yaml-rasa {4} title="endpoints.yml"
-       tracker_store:
-           type: SQL
-           dialect: "postgresql"  # the dialect used to interact with the db
-           url: "postgres"
-           db: "rasa"  # path to your db
-           username:  # username used for authentication
-           password:  # password used for authentication
-           query: # optional dictionary to be added as a query string to the connection URL
-             driver: my-driver
-     ```
+ ```yaml-rasa {4} title="endpoints.yml"
+   tracker_store:
+       type: SQL
+       dialect: "postgresql"  # the dialect used to interact with the db
+       url: "postgres"
+       db: "rasa"  # path to your db
+       username:  # username used for authentication
+       password:  # password used for authentication
+       query: # optional dictionary to be added as a query string to the connection URL
+         driver: my-driver
+ ```
 
+#### Configuration Parameters
 
+* `domain` (default: `None`): Domain object associated with this tracker store
 
-* **Parameters**
+* `dialect` (default: `sqlite`): The dialect used to communicate with your SQL backend.  Consult the [SQLAlchemy docs](https://docs.sqlalchemy.org/en/latest/core/engines.html#database-urls) for available dialects.
 
-  * `domain` (default: `None`): Domain object associated with this tracker store
+* `url` (default: `None`): URL of your SQL server
 
-  * `dialect` (default: `sqlite`): The dialect used to communicate with your SQL backend.  Consult the [SQLAlchemy docs](https://docs.sqlalchemy.org/en/latest/core/engines.html#database-urls) for available dialects.
+* `port` (default: `None`): Port of your SQL server
 
-  * `url` (default: `None`): URL of your SQL server
+* `db` (default: `rasa.db`): The path to the database to be used
 
-  * `port` (default: `None`): Port of your SQL server
+* `username` (default: `None`): The username which is used for authentication
 
-  * `db` (default: `rasa.db`): The path to the database to be used
+* `password` (default: `None`): The password which is used for authentication
 
-  * `username` (default: `None`): The username which is used for authentication
+* `event_broker` (default: `None`): Event broker to publish events to
 
-  * `password` (default: `None`): The password which is used for authentication
+* `login_db` (default: `None`): Alternative database name to which initially  connect, and create the database specified by `db` (PostgreSQL only)
 
-  * `event_broker` (default: `None`): Event broker to publish events to
+* `query` (default: `None`): Dictionary of options to be passed to the dialect and/or the DBAPI upon connect
 
-  * `login_db` (default: `None`): Alternative database name to which initially  connect, and create the database specified by `db` (PostgreSQL only)
 
-  * `query` (default: `None`): Dictionary of options to be passed to the dialect and/or the DBAPI upon connect
 
+#### Compatible Databases
 
-
-* **Officially Compatible Databases**
-
+The following databases are officially compatible with the `SQLTrackerStore`:
   * PostgreSQL
-
   * Oracle > 11.0
-
   * SQLite
 
+#### Configuring Oracle
 
+To use the SQLTrackerStore with Oracle, there are a few additional steps.
+First, create a database `tracker` in your Oracle database and create a user with access to it.
+Create a sequence in the database with the following command, where username is the user you created
+(read more about creating sequences in the [Oracle Documentation](https://docs.oracle.com/cd/B28359_01/server.111/b28310/views002.htm#ADMIN11794)):
 
-* **Oracle Configuration**
-
-  To use the SQLTrackerStore with Oracle, there are a few additional steps.
-  First, create a database `tracker` in your Oracle database and create a user with access to it.
-  Create a sequence in the database with the following command, where username is the user you created
-  (read more about creating sequences [here](https://docs.oracle.com/cd/B28359_01/server.111/b28310/views002.htm#ADMIN11794)):
-
-  ```sql
-  CREATE SEQUENCE username.events_seq;
-  ```
+```sql
+CREATE SEQUENCE username.events_seq;
+```
 
-  Next you have to extend the Rasa Open Source image to include the necessary drivers and clients.
-  First download the Oracle Instant Client from [here](https://www.oracle.com/database/technologies/instant-client/linux-x86-64-downloads.html),
-  rename it to `oracle.rpm` and store it in the directory from where you'll be building the docker image.
-  Copy the following into a file called `Dockerfile`:
+Next you have to extend the Rasa Open Source image to include the necessary drivers and clients.
+First download the [Oracle Instant Client](https://www.oracle.com/database/technologies/instant-client/linux-x86-64-downloads.html),
+rename it to `oracle.rpm` and store it in the directory from where you'll be building the docker image.
+Copy the following into a file called `Dockerfile`:
 
-  ```bash
-  FROM rasa/rasa:${variables.release}-full
+```bash
+FROM rasa/rasa:${variables.release}-full
 
-  # Switch to root user to install packages
-  USER root
+# Switch to root user to install packages
+USER root
 
-  RUN apt-get update -qq && apt-get install -y --no-install-recommends alien libaio1 && apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
+RUN apt-get update -qq && apt-get install -y --no-install-recommends alien libaio1 && apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
 
-  # Copy in oracle instaclient
-  # [https://www.oracle.com/database/technologies/instant-client/linux-x86-64-downloads.html](https://www.oracle.com/database/technologies/instant-client/linux-x86-64-downloads.html)
-  COPY oracle.rpm oracle.rpm
+# Copy in oracle instaclient
+# https://www.oracle.com/database/technologies/instant-client/linux-x86-64-downloads.html
+COPY oracle.rpm oracle.rpm
 
-  # Install the Python wrapper library for the Oracle drivers
-  RUN pip install cx-Oracle
+# Install the Python wrapper library for the Oracle drivers
+RUN pip install cx-Oracle
 
-  # Install Oracle client libraries
-  RUN alien -i oracle.rpm
+# Install Oracle client libraries
+RUN alien -i oracle.rpm
 
-  USER 1001
-  ```
+USER 1001
+```
 
-  Then build the docker image:
+Then build the docker image:
 
-  ```bash
-  docker build . -t rasa-oracle:${variables.release}-oracle-full
-  ```
+```bash
+docker build . -t rasa-oracle:${variables.release}-oracle-full
+```
 
-  Now you can configure the tracker store in the `endpoints.yml` as described above,
-  and start the container. The `dialect` parameter with this setup will be `oracle+cx_oracle`.
-  Read more about [Deploying Your Rasa Assistant](./how-to-deploy.mdx).
+Now you can configure the tracker store in the `endpoints.yml` as described above,
+and start the container. The `dialect` parameter with this setup will be `oracle+cx_oracle`.
+Read more about [Deploying Your Rasa Assistant](./how-to-deploy.mdx).
 
 
 ## RedisTrackerStore
 
+You can store your assistant's conversation history in [Redis](https://redis.io/) by using the 
+`RedisTrackerStore`.
+Redis is a fast in-memory key-value store which can optionally also persist data.
 
-* **Description**
 
-  `RedisTrackerStore` can be used to store the conversation history in [Redis](https://redis.io/).
-  Redis is a fast in-memory key-value store which can optionally also persist data.
 
+### Configuration
 
+To set up Rasa Open Source with Redis the following steps are required:
 
-* **Configuration**
+1. Start your Redis instance
 
-  To set up Rasa Open Source with Redis the following steps are required:
+2. Add required configuration to your `endpoints.yml`:
 
-  1. Start your Redis instance
+ ```yaml-rasa title="endpoints.yml"
+ tracker_store:
+     type: redis
+     url: <url of the redis instance, e.g. localhost>
+     port: <port of your redis instance, usually 6379>
+     db: <number of your database within redis, e.g. 0>
+     password: <password used for authentication>
+     use_ssl: <whether or not the communication is encrypted, default `false`>
+ ```
 
-  2. Add required configuration to your `endpoints.yml`:
+3. To start the Rasa server using your configured Redis instance,
+ add the `--endpoints` flag, e.g.:
 
-     ```yaml-rasa title="endpoints.yml"
-     tracker_store:
-         type: redis
-         url: <url of the redis instance, e.g. localhost>
-         port: <port of your redis instance, usually 6379>
-         db: <number of your database within redis, e.g. 0>
-         password: <password used for authentication>
-         use_ssl: <whether or not the communication is encrypted, default `false`>
-     ```
+ ```bash
+ rasa run -m models --endpoints endpoints.yml
+ ```
 
-  3. To start the Rasa server using your configured Redis instance,
-     add the `--endpoints` flag, e.g.:
+4. If deploying your model in Docker Compose, add the service to your `docker-compose.yml`:
 
-     ```bash
-     rasa run -m models --endpoints endpoints.yml
-     ```
+ ```yaml-rasa title="docker-compose.yml"
+ redis:
+   image: redis:latest
+ ```
 
-  4. If deploying your model in Docker Compose, add the service to your `docker-compose.yml`:
+ To route requests to the new service, make sure that the `url` in your `endpoints.yml`
+ references the service name:
 
-     ```yaml-rasa title="docker-compose.yml"
-     redis:
-       image: redis:latest
-     ```
+ ```yaml-rasa {3} title="endpoints.yml"
+  tracker_store:
+      type: redis
+      url: <url of the redis instance, e.g. localhost>
+      port: <port of your redis instance, usually 6379>
+      db: <number of your database within redis, e.g. 0>
+      password: <password used for authentication>
+      use_ssl: <whether or not the communication is encrypted, default `false`>
+ ```
 
-     To route requests to the new service, make sure that the `url` in your `endpoints.yml`
-     references the service name:
+#### Configuration Parameters
 
-     ```yaml-rasa {3} title="endpoints.yml"
-      tracker_store:
-          type: redis
-          url: <url of the redis instance, e.g. localhost>
-          port: <port of your redis instance, usually 6379>
-          db: <number of your database within redis, e.g. 0>
-          password: <password used for authentication>
-          use_ssl: <whether or not the communication is encrypted, default `false`>
-     ```
+* `url` (default: `localhost`): The url of your redis instance
 
+* `port` (default: `6379`): The port which redis is running on
 
+* `db` (default: `0`): The number of your redis database
 
-* **Parameters**
+* `password` (default: `None`): Password used for authentication
+(`None` equals no authentication)
 
-  * `url` (default: `localhost`): The url of your redis instance
+* `record_exp` (default: `None`): Record expiry in seconds
 
-  * `port` (default: `6379`): The port which redis is running on
-
-  * `db` (default: `0`): The number of your redis database
-
-  * `password` (default: `None`): Password used for authentication
-    (`None` equals no authentication)
-
-  * `record_exp` (default: `None`): Record expiry in seconds
-
-  * `use_ssl` (default: `False`): whether or not to use SSL for transit encryption
+* `use_ssl` (default: `False`): whether or not to use SSL for transit encryption
 
 
 ## MongoTrackerStore
 
 
-* **Description**
-
-  `MongoTrackerStore` can be used to store the conversation history in [Mongo](https://www.mongodb.com/).
-  MongoDB is a free and open-source cross-platform document-oriented NoSQL database.
-
+You can store your assistant's conversation history in [MongoDB](https://www.mongodb.com/) using the `MongoTrackerStore`.
+MongoDB is a free and open-source cross-platform document-oriented NoSQL database.
 
+### Configuration
 
-* **Configuration**
+1. Start your MongoDB instance.
 
-  1. Start your MongoDB instance.
+2. Add required configuration to your `endpoints.yml`:
 
-  2. Add required configuration to your `endpoints.yml`:
+ ```yaml-rasa title="endpoints.yml"
+ tracker_store:
+     type: mongod
+     url: <url to your mongo instance, e.g. mongodb://localhost:27017>
+     db: <name of the db within your mongo instance, e.g. rasa>
+     username: <username used for authentication>
+     password: <password used for authentication>
+     auth_source: <database name associated with the user's credentials>
+ ```
 
-     ```yaml-rasa title="endpoints.yml"
-     tracker_store:
-         type: mongod
-         url: <url to your mongo instance, e.g. mongodb://localhost:27017>
-         db: <name of the db within your mongo instance, e.g. rasa>
-         username: <username used for authentication>
-         password: <password used for authentication>
-         auth_source: <database name associated with the user's credentials>
-     ```
+ You can also add more advanced configurations (like enabling ssl) by appending
+ a parameter to the url field, e.g. `mongodb://localhost:27017/?ssl=true`.
 
-     You can also add more advanced configurations (like enabling ssl) by appending
-     a parameter to the url field, e.g. `mongodb://localhost:27017/?ssl=true`.
+3. To start the Rasa server using your configured MongoDB instance,
+ add the `--endpoints` flag, for example:
 
-  3. To start the Rasa server using your configured MongoDB instance,
-     add the `--endpoints` flag, for example:
+ ```bash
+ rasa run -m models --endpoints endpoints.yml
+ ```
 
-     ```bash
-     rasa run -m models --endpoints endpoints.yml
-     ```
+4. If deploying your model in Docker Compose, add the service to your `docker-compose.yml`:
 
-  4. If deploying your model in Docker Compose, add the service to your `docker-compose.yml`:
+ ```yaml-rasa title="docker-compose.yml"
+ mongo:
+   image: mongo
+   environment:
+     MONGO_INITDB_ROOT_USERNAME: rasa
+     MONGO_INITDB_ROOT_PASSWORD: example
+ mongo-express:  # this service is a MongoDB UI, and is optional
+   image: mongo-express
+   ports:
+     - 8081:8081
+   environment:
+     ME_CONFIG_MONGODB_ADMINUSERNAME: rasa
+     ME_CONFIG_MONGODB_ADMINPASSWORD: example
+ ```
 
-     ```yaml-rasa title="docker-compose.yml"
-     mongo:
-       image: mongo
-       environment:
-         MONGO_INITDB_ROOT_USERNAME: rasa
-         MONGO_INITDB_ROOT_PASSWORD: example
-     mongo-express:  # this service is a MongoDB UI, and is optional
-       image: mongo-express
-       ports:
-         - 8081:8081
-       environment:
-         ME_CONFIG_MONGODB_ADMINUSERNAME: rasa
-         ME_CONFIG_MONGODB_ADMINPASSWORD: example
-     ```
+ To route requests to this database, make sure to set the `url` in your `endpoints.yml` as the service name,
+ and specify the user and password:
 
-     To route requests to this database, make sure to set the `url` in your `endpoints.yml` as the service name,
-     and specify the user and password:
+ ```yaml-rasa {3,5,6} title="endpoints.yml"
+  tracker_store:
+      type: mongod
+      url: mongodb://mongo:27017
+      db: <name of the db within your mongo instance, e.g. rasa>
+      username: <username used for authentication>
+      password: <password used for authentication>
+      auth_source: <database name associated with the user's credentials>
+ ```
 
-     ```yaml-rasa {3,5,6} title="endpoints.yml"
-      tracker_store:
-          type: mongod
-          url: mongodb://mongo:27017
-          db: <name of the db within your mongo instance, e.g. rasa>
-          username: <username used for authentication>
-          password: <password used for authentication>
-          auth_source: <database name associated with the user's credentials>
-     ```
 
 
+#### Configuration Parameters
 
-* **Parameters**
+* `url` (default: `mongodb://localhost:27017`): URL of your MongoDB
 
-  * `url` (default: `mongodb://localhost:27017`): URL of your MongoDB
+* `db` (default: `rasa`): The database name which should be used
 
-  * `db` (default: `rasa`): The database name which should be used
+* `username` (default: `0`): The username which is used for authentication
 
-  * `username` (default: `0`): The username which is used for authentication
+* `password` (default: `None`): The password which is used for authentication
 
-  * `password` (default: `None`): The password which is used for authentication
+* `auth_source` (default: `admin`): database name associated with the user's credentials.
 
-  * `auth_source` (default: `admin`): database name associated with the user's credentials.
-
-  * `collection` (default: `conversations`): The collection name which is
-    used to store the conversations
+* `collection` (default: `conversations`): The collection name which is
+used to store the conversations
 
 
 ## DynamoTrackerStore
 
+You can store your assistant's conversation history in
+[DynamoDB](https://aws.amazon.com/dynamodb/) by using a `DynamoTrackerStore`.
+DynamoDB is a hosted NoSQL database offered by Amazon Web Services (AWS).
 
-* **Description**
-
-  `DynamoTrackerStore` can be used to store the conversation history in
-  [DynamoDB](https://aws.amazon.com/dynamodb/). DynamoDB is a hosted NoSQL
-  database offered by Amazon Web Services (AWS).
-
-
-
-* **Configuration**
 
-  1. Start your DynamoDB instance.
+### Configuration
 
-  2. Add required configuration to your `endpoints.yml`:
+1. Start your DynamoDB instance.
 
-     ```yaml-rasa title="endpoints.yml"
-     tracker_store:
-         type: dynamo
-         table_name: <name of the table to create, e.g. rasa>
-         region: <name of the region associated with the client>
-     ```
+2. Add required configuration to your `endpoints.yml`:
 
-  3. To start the Rasa server using your configured `DynamoDB` instance,
-     add the `--endpoints` flag, e.g.:
+ ```yaml-rasa title="endpoints.yml"
+ tracker_store:
+     type: dynamo
+     table_name: <name of the table to create, e.g. rasa>
+     region: <name of the region associated with the client>
+ ```
 
-     ```bash
-     rasa run -m models --endpoints endpoints.yml
-     ```
+3. To start the Rasa server using your configured `DynamoDB` instance,
+ add the `--endpoints` flag, e.g.:
 
+ ```bash
+ rasa run -m models --endpoints endpoints.yml
+ ```
 
 
-* **Parameters**
+#### Configuration Parameters
 
-  * `table_name` (default: `states`): name of the DynamoDB table
+* `table_name` (default: `states`): name of the DynamoDB table
 
-  * `region` (default: `us-east-1`): name of the region associated with the client
+* `region` (default: `us-east-1`): name of the region associated with the client
 
 
 ## Custom Tracker Store
 
-If you require a tracker store which is not available out of the box, you can implement your own.
+If you need a tracker store which is not available out of the box, you can implement your own.
 This is done by extending the base class `TrackerStore`.
 
 To write a custom tracker store, extend the `TrackerStore` base class. Your constructor has to
 provide a parameter `host`.
 
-* **Configuration**
-
-     In your `endpoints.yml` put in the module path to your custom tracker store
-     and the parameters you require:
-
-     ```yaml-rasa title="endpoints.yml"
-     tracker_store:
-       type: path.to.your.module.Class
-       url: localhost
-       a_parameter: a value
-       another_parameter: another value
-     ```
-
-    If you are deploying in Docker Compose, you have two options to add this store to Rasa Open Source:
-    extending the Rasa image to include the module, or mounting the module as volume.
-
-     Make sure to add the corresponding service as well. For example, mounting it as a volume would look like so:
-
-     ```yaml {5,6,7} title="docker-compose.yml"
-     rasa:
-       <existing rasa service configuration>
-       volumes:
-         - <existing volume mappings, if there are any>
-         - ./path/to/your/module.py:/app/path/to/your/module.py
-     custom-tracker-store:
-       image: custom-image:tag
-     ```
-
-     ```yaml-rasa {3} title="endpoints.yml"
-     tracker_store:
-       type: path.to.your.module.Class
-       url: custom-tracker-store
-       a_parameter: a value
-       another_parameter: another value
-     ```
+### Configuration
+
+ In your `endpoints.yml` put in the module path to your custom tracker store
+ and the parameters you require:
+
+ ```yaml-rasa title="endpoints.yml"
+ tracker_store:
+   type: path.to.your.module.Class
+   url: localhost
+   a_parameter: a value
+   another_parameter: another value
+ ```
+
+If you are deploying in Docker Compose, you have two options to add this store to Rasa Open Source:
+extending the Rasa image to include the module, or mounting the module as volume.
+
+ Make sure to add the corresponding service as well. For example, mounting it as a volume would look like so:
+
+ ```yaml {5,6,7} title="docker-compose.yml"
+ rasa:
+   <existing rasa service configuration>
+   volumes:
+     - <existing volume mappings, if there are any>
+     - ./path/to/your/module.py:/app/path/to/your/module.py
+ custom-tracker-store:
+   image: custom-image:tag
+ ```
+
+ ```yaml-rasa {3} title="endpoints.yml"
+ tracker_store:
+   type: path.to.your.module.Class
+   url: custom-tracker-store
+   a_parameter: a value
+   another_parameter: another value
+ ```
diff --git a/docs/docs/training-data-format.mdx b/docs/docs/training-data-format.mdx
index 66416d6839e3..6ddbc1de461c 100644
--- a/docs/docs/training-data-format.mdx
+++ b/docs/docs/training-data-format.mdx
@@ -235,7 +235,10 @@ name of your intents.
 
 ### Entities
 
-[Entities](glossary.mdx#entity) are structured pieces of information that can be extracted from a user's message. For entity extraction to work, you need to either specify training data to train an ML model or you need to define [regular expressions](#regular-expressions-for-entity-extraction) to extract entities using the [`RegexEntityExtractor`](components.mdx#regexentityextractor) based on a character pattern.
+[Entities](glossary.mdx#entity) are structured pieces of information that can be extracted from a user's message.
+For entity extraction to work, you need to either specify training data to train an ML model or you need
+to define [regular expressions](#regular-expressions-for-entity-extraction) to extract entities
+using the [`RegexEntityExtractor`](components.mdx#regexentityextractor) based on a character pattern.
 
 Entities are annotated in training examples with minimally the entity's name.
 In addition to the entity name, you can annotate an entity with synonyms, roles, or groups.
@@ -427,9 +430,9 @@ sure your lookup tables contain clean data!
 
 Stories and rules are both representations of conversations between a user
 and a conversational assistant. They are used to train the dialogue management
-model. [**Stories**](stories.mdx) are used to train a machine learning model
+model. [Stories](stories.mdx) are used to train a machine learning model
 to identify patterns in conversations and generalize to unseen conversation paths.
-**[Rules](rules.mdx)** describe small pieces of conversations that should always
+[Rules](rules.mdx) describe small pieces of conversations that should always
 follow the same path and are used to train the
 [RulePolicy](policies.mdx#rule-policy).
 
@@ -517,7 +520,7 @@ by the name of the action.
 While writing stories, you will encounter two types of actions:
 
 
-1. [**Responses**](domain.mdx#responses): start with `utter_` and
+1. [Responses](domain.mdx#responses): start with `utter_` and
    send a specific message to the user. e.g.
 
 ```yaml-rasa {5}
@@ -528,7 +531,7 @@ stories:
   - action: utter_greet
 ```
 
-2. [**Custom actions**](custom-actions.mdx): start with `action_`, run
+2. [Custom actions](custom-actions.mdx): start with `action_`, run
    arbitrary code and send any number of messages (or none).
 
 ```yaml-rasa {5}
@@ -730,7 +733,7 @@ rules:
   - action: utter_greet
 ```
 
-Read more about writing rules [here](rules.mdx#writing-a-rule).
+For more information about writing rules, see [Rules](rules.mdx#writing-a-rule).
 
 ## Test Conversations
 
diff --git a/docs/docs/tuning-your-model.mdx b/docs/docs/tuning-your-model.mdx
index 8f88b83ae4fc..46b65ff7fe3e 100644
--- a/docs/docs/tuning-your-model.mdx
+++ b/docs/docs/tuning-your-model.mdx
@@ -130,7 +130,11 @@ The image below shows the call order during the training of this pipeline:
 
 
 
-<img alt="Component Lifecycle" src={useBaseUrl("/img/component_lifecycle.png")} />
+<img caption="Component Lifecycle" src={useBaseUrl("/img/component_lifecycle.png")
+alt="The component lifecycle during training. Components are processed in the order
+they're listed in the configuration file.
+All components are created and initialized in order before they are trained in
+order and then persisted in order."} />
 
 Before the first component is created using the `create` function, a so
 called `context` is created (which is nothing more than a python dict).
diff --git a/docs/docs/unexpected-input.mdx b/docs/docs/unexpected-input.mdx
index 97ce563c9df3..58d9c566a95d 100644
--- a/docs/docs/unexpected-input.mdx
+++ b/docs/docs/unexpected-input.mdx
@@ -39,7 +39,7 @@ One common case of contextual interjections is during slot filling for [form](fo
 asks “Why do you need to know that?” or "Can you explain that?".
 The response should differ for each slot. For example:
 
-<Chat caption="Contextual interjection">
+<Chat caption="A contextual interjection">
 <ChatUserText>Hi</ChatUserText>
 <ChatBotText>Hello! I am restaurant search assistant! How can I help?</ChatBotText>
 <ChatUserText>I'm looking for a restaurant</ChatUserText>
diff --git a/docs/docs/writing-stories.mdx b/docs/docs/writing-stories.mdx
index 0edbc551ea7c..829330413ddc 100644
--- a/docs/docs/writing-stories.mdx
+++ b/docs/docs/writing-stories.mdx
@@ -399,7 +399,7 @@ In some cases, such as single-turn interjections, you can handle context-switchi
 using [rules](./rules.mdx) instead of through [stories](./stories.mdx).
 
 Consider this conversation scenario:
-<Chat caption="Single-turn interjection">
+<Chat caption="A single-turn interjection">
 <ChatUserText>Hi, I want to pay my credit card bill</ChatUserText>
 <ChatBotText>Can do! Which of these credit accounts do you want to make a payment towards?</ChatBotText>
 <ChatBotText><p>- Credit Account A</p>
@@ -440,7 +440,7 @@ is maintained.
 For example, if you want to switch context upon a user ask and then return to the
 original flow after that ask is complete:
 
-<Chat caption="Contextual interjection">
+<Chat caption="A contextual interjection">
 <ChatUserText>Hi, I want to pay my credit card bill</ChatUserText>
 <ChatBotText>Can do! Which of these credit accounts do you want to make a payment towards?</ChatBotText>
 <ChatBotText><p>- Credit Account A</p>


Code review comments:
diff_hunk: @@ -13,27 +13,22 @@ responds to a message:
 
 
 
-<img alt="image" src={useBaseUrl("/img/rasa-message-processing.png")} />
+<img caption="Rasa Open Source architecture" src={useBaseUrl("/img/rasa-message-processing.png")}
path: docs/docs/architecture.mdx
text: @user1:
This will work, but for raster sources it's better for performance to use the `<Image />` component in the way we discussed in Slack, and also, it's arguably better to place the image next to the doc and reference it relatively. This way it will be versioned along with the docs, and we avoid:

1. a potentially orphaned image in the `static` folder
2. an image which is up-to-date with current docs but no longer the right image for the older versions

@author:
what do you mean by `place the imge next to the doc`? as in sth like `docs/docs/architecture-img.png`?

@user1:
Yes, that's what I mean 😄 . So then, taking that example, your code, assuming the MDX file is in the same directory, would look something like

```jsx
import archImage from './architecture-img.png';

<Image img={archImage} alt='this text will be invisble, in the alt attribute of the img' caption='this text will be visible, in the figcaption following the img' />
```

diff_hunk: @@ -12,7 +12,7 @@ Once you have them you can add these to your `credentials.yml`.
 
 **How to get the Slack credentials:** You need to set up a Slack app.
 
-1. To create the app go to [https://api.slack.com/apps](https://api.slack.com/apps) and click
+1. To create the app go to [Your Apps](https://api.slack.com/apps) and click
path: docs/docs/connectors/slack.mdx
text: @user1:
From an a11y POV this link is a little bare, since the text "Your Apps" which would be read out-of-context by someone navigating with assistive tech, is not self-explanatory. You can add a title to a link like this
```md
To create the app go to [Your Apps](https://api.slack.com/apps "The Your Apps section of your Slack interface")
```

@author:
Ooh i did not know this! that's super helpful

diff_hunk: @@ -130,7 +130,11 @@ The image below shows the call order during the training of this pipeline:
 
 
 
-<img alt="Component Lifecycle" src={useBaseUrl("/img/component_lifecycle.png")} />
+<img caption="Component Lifecycle" src={useBaseUrl("/img/component_lifecycle.png")
+alt="The component lifecycle during training. Components are processed in the order
+they're listed in the configuration file.
+All components are created and initialized in order before they are trained in
+order and then persisted in order."} />
path: docs/docs/tuning-your-model.mdx
text: @user1:
I think you might want to reverse `caption` and `alt` here—and use an `Image` component for this since `caption` won't do anything to an HTML `img` tag. Also same comment as above re versioning