CXP-1208: wip docs catalogs

Author: tseho

content/apps/catalogs.md

@@ -2,26 +2,35 @@
 
 ## Overview
 
-<!-- TODO -->
-
-This guide introduces the catalog feature, which avoids you to add a filtering interface to your app as Akeneo PXM Studio already does it.
+This guide introduces the catalog feature. With catalogs, you will save time during development because Akeneo PXM Studio
+will manage your **product selection** and give you direct access to the relevant data.
+With catalogs, you don't need to develop interfaces about filtering products, locales or attributes.
 
 ### What's a catalog?
 
-With catalogs, Akeneo users can configure which products they want to share with your app thanks to a **product selection** composed of one or several criteria that allow you to filter products. 
+A catalog is a selection of products defined by one or several criteria. (families, categories, ...)
+
+Catalogs are only created by apps and are configured by Akeneo users themselves from Akeneo PXM Studio. This feature is
+only visible if the app manage catalogs.
 
-When your app uses catalogs to retrieve product data, it automatically enables the Catalogs tab and creates catalogs in Akeneo.
+![Catalogs](../img/apps/catalogs-list.png)
 
-<!-- image catalog list -->
+![Product Selection](../img/apps/catalogs-product-selection.png)
+
+### Limits
+
+::: warning
+You can create **up to 15 catalogs** per app.
+:::
 
 ### Next steps
 
 - Learn [how to create and use catalogs](/apps/catalogs.html#getting-started-with-catalogs)
-- Discover how users configure catalogs in the Akeneo PXM Studio <!-- TODO Add link -->
+<!-- - Discover how users configure catalogs in the Akeneo PXM Studio TODO Add link -->
 
 ## Getting started with catalogs
 
-<!-- `Add an introduction` -->
+To create and use a catalog, an app must send some requests to the PIM REST API.
 
 ### What you'll learn
 
@@ -34,17 +43,38 @@ After you've completed this tutorial, you'll be able to create and use catalogs
 
 ### Step 1: Ask for catalog scopes
 
-<!-- TODO -->
+In the documentation [Ask for authorizations](/apps/authentication-and-authorization.html#step-2-ask-for-authorizations), 
+you discovered how to ask for scopes.
+
+If you want to manage catalogs, you need to ask for 4 scopes:
+- `read_products`
+- `read_catalogs`
+- `write_catalogs`
+- `delete_catalogs`
+
+Once these scopes are accepted by Akeneo users during the installation of your app, you will be able to manage and use
+catalogs.
 
 ### Step 2: Create catalogs
 
-<!-- TODO -->
+Checkout the [Create a new catalog](/api-reference.html#post_app_catalog) endpoint documentation to find out how
+to create one.
 
-By default, when you create a catalog in the Akeneo PXM Studio, the catalog is disabled. It means that, until a user hasn't enabled it, you won't be able to retrieve products for this catalog. Note that only users can enable a catalog. 
+::: info
+You should create a catalog with the more descriptive name possible. It will help your users to know how to configure it.
+:::
 
-::: warning
-You can create **up to 15 catalogs** per app.
-::: 
+Catalogs created **are always disabled by default** in the Akeneo PXM Studio. Only Akeneo users are able to enable a 
+catalog. You must wait for one of your user to enable it before using it.
+
+To help your users, you can give them a link to directly access the catalog configuration interface:
+
+``` http
+
+https://my-pim.cloud.akeneo.com/connect/apps/v1/catalogs/{catalog id}
+```
+
+At any moment, you can verify if the catalog is enabled by calling the [get catalog endpoint](/api-reference.html#get_app_catalog).
 
 ### Step 3: Get products using catalogs