Repository: RasaHQ/rasa
Pull request: Update outdated docs content
**Proposed changes**:
- Update any outdated content in the docs
- closes https://github.com/RasaHQ/rasa/issues/6775

**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:
finish old content check in docs
- [x] Nlu data format 
- [x] responses?
- [x] domain.mdx (There are outstanding TODOs here, and the unfeaturized_slot PR also updates this page)
- [x] event-brokers.mdx
- [x] fallback-handoff.mdx
- [x] forms.mdx (have looked through it, changes also coming in from unfeaturized_slot PR)
- [x] generating-nlu-data.mdx
- [x] glossary.mdx (maybe check the notes entered next to Rasa NLU and Rasa Core)
- [x] how-to-deploy.mdx
- [x] http-api.mdx
- [x] installation.mdx
- [x] introduction.mdx
- [x] jupyter-notebooks.mdx
- [x] lock-stores.mdx
- [x] messaging-and-voice-channels.mdx (and all the channels associated with it)
- [x] migrate-from.mdx (and all the pages associated with it) 
- [x] migration-guide.mdx
- [x] model-configuration.mdx
- [x] the `docker` subfolder

Hints from issue discussion:
@akelad update this
@melindaloubser1 @b-quachtran, if you have some time, could you take on a few of these? The idea is just to go through the page and see if there's any outdated information on them, it's entirely possible that a lot of them don't need any edits. 
Sure, I'm already working on NLU data format, and I'll see how many others I can get through today. @b-quachtran if you want to make sure we don't look at the same ones you can start at http-api?
@melindaloubser1 Sounds good, although I probably won't be able to get to this until early next week
You can work on the `old_content_check` branch if you'd like. 
@melindaloubser1 @erohmensing whats up with this issue? anything that needs to be done before the 2.0 release today?
hm, not sure what happened with Ben's section of this, but we want to merge Melinda's two PRs mentioned for sure. The rest won't make it I guess
I'll remove this issue then, please add the prs separately to the milestone

Commit message: Apply suggestions from code review

Co-authored-by: Akela Drissner-Schmid <32450038+akelad@users.noreply.github.com>

Patch to review:
diff --git a/docs/docs/event-brokers.mdx b/docs/docs/event-brokers.mdx
index 41cb05343627..1cb1b51474e3 100644
--- a/docs/docs/event-brokers.mdx
+++ b/docs/docs/event-brokers.mdx
@@ -7,7 +7,7 @@ description: Find out how open source chatbot framework Rasa allows you to strea
 
 An event broker allows you to connect your running assistant to other services that process the data coming
 in from conversations. For example, you could [connect your live assistant to
-Rasa X](https://rasa.com/docs/rasa-x/installation-and-setup/deploy#connect-rasa-deployment/)
+Rasa X](https://rasa.com/docs/rasa-x/installation-and-setup/deploy#connect-an-existing-deployment)
 to review and annotate conversations or forward messages to an external analytics
 service. The event broker publishes messages to a message streaming service,
 also known as a message broker, to forward Rasa [Events](https://rasa.com/docs/action-server/events) from the Rasa server to other services.
@@ -32,7 +32,7 @@ tracker looks like this:
 ```
 
 The `event` field takes the event's `type_name` (for more on event
-types, check out the [Events](https://rasa.com/docs/action-server/events) docs).
+types, check out the [events](https://rasa.com/docs/action-server/events) docs).
 
 ## Pika Event Broker
 
@@ -103,7 +103,7 @@ if __name__ == '__main__':
 
 ## Kafka Event Broker
 
-It is possible to use [Kafka](https://kafka.apache.org/) as main broker for your
+It is possible to use [Kafka](https://kafka.apache.org/) as the main broker for your
 events. In this example we are going to use the [python-kafka](https://kafka-python.readthedocs.io/en/master/usage.html) library, a Kafka client written in Python.
 
 ### Adding a Kafka Event Broker Using the Endpoint Configuration
@@ -111,12 +111,12 @@ events. In this example we are going to use the [python-kafka](https://kafka-pyt
 You can instruct Rasa to stream all events to your Kafka event broker by adding an `event_broker` section to your
 `endpoints.yml`.
 
-Using `SASL_PLAINTEXT` protocol the endpoints file must have the following entries:
+Using the `SASL_PLAINTEXT` protocol the endpoints file must have the following entries:
 
 ```yaml-rasa (docs/sources/data/test_endpoints/event_brokers/kafka_plaintext_endpoint.yml)
 ```
 
-If using SSL protocol, the endpoints file should look like:
+If using the `SSL` protocol, the endpoints file should look like:
 
 ```yaml-rasa (docs/sources/data/test_endpoints/event_brokers/kafka_ssl_endpoint.yml)
 ```
@@ -138,7 +138,7 @@ tracker_store = InMemoryTrackerStore(domain=domain, event_broker=kafka_broker)
 The host variable can be either a list of brokers addresses or a single one.
 If only one broker address is available, the client will connect to it and
 request the cluster Metadata.
-Therefore, the remain brokers in the cluster can be discovered
+Therefore, the remaining brokers in the cluster can be discovered
 automatically through the data served by the first connected broker.
 
 To pass more than one broker address as argument, they must be passed in a
@@ -153,7 +153,7 @@ kafka_broker = KafkaEventBroker(host=['kafka_broker_1:9092',
 
 ### Authentication and Authorization
 
-Rasa's Kafka producer accepts two types of security protocols - `SASL_PLAINTEXT` and `SSL`.
+Rasa's Kafka producer accepts two types of security protocols: `SASL_PLAINTEXT` and `SSL`.
 
 For development environment, or if the brokers servers and clients are located
 into the same machine, you can use simple authentication with `SASL_PLAINTEXT`.
@@ -172,7 +172,7 @@ kafka_broker = KafkaEventBroker(host='kafka_broker:9092',
 ```
 
 If the clients or the brokers in the kafka cluster are located in different
-machines, it's important to use ssl protocol to assure encryption of data and client
+machines, it's important to use the `SSL` protocol to ensure encryption of data and client
 authentication. After generating valid certificates for the brokers and the
 clients, the path to the certificate and key generated for the producer must
 be provided as arguments, as well as the CA's root certificate.
@@ -193,7 +193,7 @@ and inter-broker connections to prevent man-in-the-middle attacks.
 
 ### Implementing a Kafka Event Consumer
 
-The parameters used to create a Kafka consumer are the same used on the producer creation,
+The parameters used to create a Kafka consumer are the same as those used in the producer creation,
 according to the security protocol being used. The following implementation shows an example:
 
 ```python
@@ -219,16 +219,16 @@ It is possible to use an SQL database as an event broker. Connections to databas
 [SQLAlchemy](https://www.sqlalchemy.org/), a Python library which can interact with many
 different types of SQL databases, such as [SQLite](https://sqlite.org/index.html),
 [PostgreSQL](https://www.postgresql.org/) and more. The default Rasa installation allows connections to SQLite
-and PostgreSQL databases, to see other options, please see the
+and PostgreSQL databases. To see other options, please see the
 [SQLAlchemy documentation on SQL dialects](https://docs.sqlalchemy.org/en/13/dialects/index.html).
 
 ### Adding a SQL Event Broker Using the Endpoint Configuration
 
 To instruct Rasa to save all events to your SQL event broker, add an `event_broker` section to your
 `endpoints.yml`. For example, a valid SQLite configuration
-could look like the following:
+could look like this:
 
-```yaml-rasa
+```yaml-rasa title="endpoints.yml"
 event_broker:
   type: SQL
   dialect: sqlite
@@ -237,7 +237,7 @@ event_broker:
 
 PostgreSQL databases can be used as well:
 
-```yaml-rasa
+```yaml-rasa title="endpoints.yml"
 event_broker:
   type: SQL
   url: 127.0.0.1
diff --git a/docs/docs/forms.mdx b/docs/docs/forms.mdx
index c79a14f9d706..9b53b54b7626 100644
--- a/docs/docs/forms.mdx
+++ b/docs/docs/forms.mdx
@@ -2,12 +2,12 @@
 id: forms
 sidebar_label: Forms
 title: Forms
-description: Follow a rule-based process of information gathering using FormActions in open source bot framework Rasa.
----
+description: Follow a rule-based process of information gathering using forms in open source bot framework Rasa.
+abstract: One of the most common conversation patterns is to collect a few pieces of
+          information from a user in order to do something (book a restaurant, call an
+          API, search a database, etc.). This is also called **slot filling**.
 
-One of the most common conversation patterns is to collect a few pieces of
-information from a user in order to do something (book a restaurant, call an
-API, search a database, etc.). This is also called **slot filling**.
+---
 
 ## Usage
 
@@ -22,10 +22,10 @@ policies:
 
 ### Defining a Form
 
-Define a form by adding it to the `forms` section in your [Domain](./domain.mdx).
+Define a form by adding it to the `forms` section in your [domain](./domain.mdx).
 The name of the form is also the name of the action which you can use in
-[Stories](./stories.mdx) or [Rules](./rules.mdx) to handle form executions. Further you
-need to define [Slot Mappings](./forms.mdx#slot-mappings) for each slot which your
+[stories](./stories.mdx) or [rules](./rules.mdx) to handle form executions. You also
+need to define [slot mappings](./forms.mdx#slot-mappings) for each slot which your
 form should fill.
 You can specify one or more slot mappings for each slot to be filled.
 
@@ -52,7 +52,7 @@ each required slot.
 
 ### Activating a Form
 
-To activate a form you need to add a [Story](./stories.mdx) or [Rule](./rules.mdx),
+To activate a form you need to add a [story](./stories.mdx) or [rule](./rules.mdx),
 which describes when the assistant should run the form. In the case a specific intent
 triggering a form, you can for example use the following rule:
 
@@ -102,7 +102,7 @@ write stories or rules for this case.
 
 ### Slot Mappings
 
-Rasa Open Source comes with four predefined functions to fill the slots of a form
+Rasa Open Source comes with four predefined mappings to fill the slots of a form
 based on the latest user message. Please see
 [Custom Slot Mappings](./forms.mdx#custom-slot-mappings) if you need a custom function
 to extract the required information.
@@ -191,7 +191,7 @@ apply if the intent of the message is `excluded_intent`. Note that you can
 also define lists of intents for the parameters `intent` and `not_intent`.
 
 :::note
-The slot mapping will not apply during the initial activation of the form. To fill
+The `from_intent` slot mapping will not apply during the initial activation of the form. To fill
 a slot based on the intent that activated the form, use the `from_trigger_intent`
 mapping.
 :::
@@ -494,16 +494,3 @@ class AskForSlotAction(Action):
         return []
 ```
 
-## Debugging
-
-The first thing to try is running your bot with the `--debug` flag, see
-[Command Line Interface](./command-line-interface.mdx) for details.
-If you are just getting started, you probably only have a few hand-written stories.
-This is a great starting point, but
-you should give your bot to people to test **as soon as possible**. One of the guiding principles
-behind Rasa Core is:
-
-> Learning from real conversations is more important than designing hypothetical ones
-
-So don't try to cover every possibility in your hand-written stories before giving it to testers.
-Real user behavior will always surprise you!
diff --git a/docs/docs/generating-nlu-data.mdx b/docs/docs/generating-nlu-data.mdx
index a6120c950d63..2768b22b05cf 100644
--- a/docs/docs/generating-nlu-data.mdx
+++ b/docs/docs/generating-nlu-data.mdx
@@ -143,7 +143,7 @@ For example, in an assistant that asks users what insurance policies they're int
 in, they might respond with "my truck," "a car," or "I drive a batmobile."
 It would be a good idea to map `truck`, `car`, and `batmobile` to the normalized value
 `auto` so that the processing logic will only need to account for a narrow set of
-possibilities (see [Entity Synonyms](./training-data-format.mdx#synonyms)).
+possibilities (see [synonyms](./training-data-format.mdx#synonyms)).
 
 ## Handling Edge Cases
 
diff --git a/docs/docs/glossary.mdx b/docs/docs/glossary.mdx
index 546832f72189..f57673c099f3 100644
--- a/docs/docs/glossary.mdx
+++ b/docs/docs/glossary.mdx
@@ -75,7 +75,7 @@ description: Glossary for all Rasa-related terms
 
 ## Retrieval Intent
 
-  A special instance of an intent which can be divided into smaller sub-intents. Each sub-intent has a fixed response and hence the context of the conversation does not matter when user expresses one of these sub-intents.
+  A special instance of an intent which can be divided into smaller sub-intents. Each sub-intent has a fixed response and hence the context of the conversation does not matter when a user expresses one of these sub-intents.
 
 ## [Interactive Learning](./writing-stories.mdx#using-interactive-learning)
 
@@ -107,10 +107,14 @@ description: Glossary for all Rasa-related terms
 
 ## Rasa Core
 
+  (Outdated - Rasa Core and Rasa NLU were merged into one package in 1.x. The functionality of Core is now referred to as dialogue management)
+  
   The dialogue engine that decides on what to do next in a conversation based on the context.
 
 ## Rasa NLU
 
+  (Outdated - Rasa Core and Rasa NLU were merged into one package in 1.x. The functionality of Rasa NLU is now referred to as NLU)
+
   Rasa NLU is the part of Rasa that performs Natural Language Understanding ([NLU](#nlu)), including intent classification and entity extraction.
 
 ## [Response / Template / Utterance](./responses.mdx)
@@ -129,7 +133,7 @@ description: Glossary for all Rasa-related terms
 
 ## [Story](./stories.mdx)
 
-  A conversation between a user and a bot annotated with the intent / entities of the users' messages as well as the sequence of actions to be performed by the bot
+  A representation of a conversation between a user and a bot. A story includes the intent / entities of the users' messages as well as the sequence of actions to be performed by the bot
 
 ## User Goal
 
diff --git a/docs/docs/how-to-deploy.mdx b/docs/docs/how-to-deploy.mdx
index 95a2c40d5bf8..afeb705e7fa5 100644
--- a/docs/docs/how-to-deploy.mdx
+++ b/docs/docs/how-to-deploy.mdx
@@ -16,7 +16,7 @@ important happy paths or is what we call a [minimum viable assistant](./glossary
 
 The recommended deployment methods described below make it easy to share your assistant
 with test users via the [share your assistant feature in
-Rasa X](https://rasa.com/docs/rasa-x/user-guide/share-assistant/#share-your-bot).
+Rasa X](https://rasa.com/docs/rasa-x/user-guide/share-assistant#share-your-bot).
 Then, when you're ready to make your assistant available via one or more [Messaging and Voice Channels](./messaging-and-voice-channels.mdx),
 you can easily add them to your existing deployment set up.
 
diff --git a/docs/docs/responses.mdx b/docs/docs/responses.mdx
index 189ddd2731a4..e8fdc23b9dba 100644
--- a/docs/docs/responses.mdx
+++ b/docs/docs/responses.mdx
@@ -7,10 +7,9 @@ abstract: Responses are messages that your assistant sends to the user. A respon
 ---
 ## Defining Responses
 
-Responses go under the `responses` key in your [domain](./domain.mdx) file. Start each
-response name with `utter_`.
 
-Here is an example of a domain file with two responses called `utter_greet` and `utter_bye`:
+Responses go under the `responses` key in your domain file or in a separate "responses.yml" file. Each response name should start with `utter_`.
+For example, you could add responses for greeting and saying goodbye under the response names `utter_greet` and `utter_bye`:
 
 ```yaml-rasa {4-8} title="domain.yml"
 intents:
@@ -23,8 +22,9 @@ responses:
   - text: "See you!"
 ```
 
-If you use [retrieval intents](./glossary.mdx#retrieval-intent), make sure you define the responses 
-for each retrieval intent in your domain file, like in the following example:
+
+If you are using [retrieval intents](glossary.mdx#retrieval-intent) in your assistant, you also need to add responses
+for your assistant's replies to these intents:
 
 ```yaml-rasa {5-6,8-9}
 intents:
@@ -62,7 +62,8 @@ filled with `None`.
 
 Another way to fill in a variable is within a [custom action](./custom-actions.mdx).
 In your custom action code, you can supply values to a response to fill in specific variables. 
-If you use Rasa SDK for your action server, you can do this using `dispatcher.utter_message`:
+If you're using the Rasa SDK for your action server,
+you can pass a value for the variable as a keyword argument to [`dispatcher.utter_message`](https://rasa.com/docs/action-server/sdk-dispatcher):
 
 ```python {3}
 dispatcher.utter_message(
@@ -221,8 +222,10 @@ responses:
 
 ### Calling Responses as Actions
 
-So long as the name of the response starts with `utter_`, the response can
-directly be used as an action. Say you have the following response in your domain:
+If the name of the response starts with `utter_`, the response can
+directly be used as an action, without being listed in the `actions` section of your domain. You would add the response
+to the domain:
+
 
 ```yaml-rasa title="domain.yml"
 responses:
@@ -250,10 +253,9 @@ you need to retrain the assistant before these changes will be picked up.
 
 ### Calling Responses from Custom Actions
 
-If you use Rasa SDK as your action server, you can call responses from your
-[Custom Actions](custom-actions.mdx) by using the `dispatcher`
-variable. In your custom action code, you can
-send a message based on the responses defined under `utter_greet` like this:
+
+You can use the responses to generate response messages from your
+custom actions. If you're using Rasa SDK as your action server, you can use the dispatcher to generate the response message, for example: 
 
 ```python {8} title="actions.py"
 from rasa_sdk.interfaces import Action


Code review comments:
diff_hunk: @@ -2,12 +2,12 @@
 id: forms
 sidebar_label: Forms
 title: Forms
-description: Follow a rule-based process of information gathering using FormActions in open source bot framework Rasa.
----
+description: Follow a rule-based process of information gathering using forms in open source bot framework Rasa.
+abstract: One of the most common conversation patterns is to collect a few pieces of
+          information from a user in order to do something (book a restaurant, call an
+          API, search a database, etc.). This is also called **slot filling**.
 
path: docs/docs/forms.mdx
text: @user1:
```suggestion
```