IBX-5808 - Improve "Products" to remove ambiguity

docs/pim/create_product_types.md

@@ -31,6 +31,7 @@ When you define attributes for the product type, you can add or remove either wh
 You can also remove whole groups, or single attributes from groups that you don't want to use for the given product type.
 Do this by clicking the **X** icon next to the group or attribute.
 
+<a name="vat"></a>
 For every attribute, you can select **Used for product variants**.
 Attributes that have this option are used to [automatically generate product variants](work_with_product_variants.md#generate-variants).
 

docs/pim/manage_availability_and_stock.md

@@ -1,19 +1,24 @@
 ---
-description: Products in catalog can be made unavailable, either in certain quantity or with infinite stock.
+description: Products can be made unavailable or available, either in certain quantity or with infinite stock.
 ---
 
 # Work with availability and stock
 
-[Products in catalog](products.md#products) can be unavailable, or can be made available in certain quantity, or with infinite stock.
+Products can be unavailable or available, either in certain quantity or with infinite stock.
+Being available translates into being offered for purchase.
+
+You can control the product's availability, and the available stock.
+When setting stock, you can set the exact number of pieces, or indicate that stock is infinite, for example, for digital, downloadable products.
+
+If a product has variants, you must set availability and stock for each variant separately.
 
 ## Set product availability
 
-To control a product's availability and the available stock, in product or variant view go to **Availability** tab.
-If a product can have variants, you must set availability for each variant separately.
+To control the availability and stock, in product or product variant view, go to **Availability** tab.
 
 ![Product availability](img/product_availability_tab.png "Product availability")
 
-In the **Availability** tab, click **Create** to add availability to a product that doesn't have it,
+Then, click **Create** to add availability to a product that doesn't have it,
 or **Edit** to modify existing availability settings.
 
 Use the **Available** switcher to indicate whether the product is currently available in the catalog.

docs/pim/manage_prices.md

@@ -2,14 +2,12 @@
 description: Products can have a base price and custom prices defined per customer group and per currency.
 ---
 
-# Work with prices
+# Work with product prices
 
-[Products in catalog](products.md#products) can have a base price and custom prices defined per [customer group](../customer_management/manage_customers.md) and per [currency](../pim/manage_currencies.md).
+[Products](products.md) and product [variants](work_with_product_variants.md) can have a base price and multiple custom prices.
+Prices can differ depending on [customer group](../customer_management/manage_customers.md) and [currency](../pim/manage_currencies.md) and be applied according to the rules.
 
-With price management features, you set up product prices manually. 
-A price can be set up per product and product variant.
-
-In addition, prices can vary per [customer group](../customer_management/customer_portal.md).
+With price management features, you set up product prices manually.
 
 !!! note
 

docs/pim/pim.md

@@ -0,0 +1,24 @@
+---
+description: PIM enables handling of products presented in the website anf offered in the storefront, including their specifications and pricing.
+---
+
+# PIM (Product Information Management)
+
+With PIM you can create, configure and manage products that are offered in the [[= product_name =]]-based website and/or storefront, including their specifications, attributes, assets, variants and pricing.
+
+You can group products into categories and catalogs.
+Catalogs are collections of products selected by using configurable filters.
+Categories let you organize products within PIM and create relationships between them, for example, to help customers in searching for products.
+
+PIM's features are available from the left-hand menu.
+
+![PIM in the menu](img/catalog_menu.png "PIM in the menu")
+
+[[= cards([
+    "pim/product_types",
+    "pim/create_product_types",
+    "pim/products",
+    "pim/create_edit_product",
+    "pim/work_with_catalogs",
+    "pim/work_with_product_categories"
+], columns=3) =]] 

docs/pim/product_types.md

@@ -0,0 +1,36 @@
+---
+description: Product types contain a combination of Fields and attributes and serve as templates for different types of products.
+---
+
+# Product types
+
+Product types are templates that contain a combination of [Fields](../content_management/content_model.md#fields-and-field-types) and [attributes](#attributes) which constitute a product definition.
+By default, product types contain such Fields as name, specification, image, or category.
+You can modify them as required.
+You need different product types, because products of type "Laptops" contain different Fields and attributes than those of type "White appliances".
+
+When you create a new product type, you can choose between two available product type flavors: Physical and Virtual:
+
+- Physical - tangible products.
+They can use measurement attributes. They require shipment in the online purchase process.
+Examples: heaters, laptops, phones.
+- Virtual - non-tangible items. They can be sold individually, or as part of a product bundle.
+They don't require shipment in the online process. Examples: memberships, services, warranties. 
+
+A product type also defines both the attributes and VAT rates for all its products.
+
+When a product type is created, you can review its fields, attributes, and VAT rate settings on the product type's details screen, without having to open it for editing.
+
+![VAT rates in product type's details view](img/vat_rates_product_details.png "VAT rates in product type's details view")
+
+If your [user Role](../permission_management/work_with_permissions.md) has the `ProductType/Edit` 
+permission, you can [modify product types and add individual attributes or attribute groups](create_product_types.md).
+
+### Attributes
+
+Attributes describe product characteristics.
+Customers can use them to filter and search for products.
+Attribute types define what kind of information you can store in an attribute.
+Typical product attribute examples include dimensions, weight, color, or format.
+
+For more information, see [Work with product attributes](work_with_product_attributes.md).

docs/pim/products.md

@@ -4,73 +4,34 @@ description: Products are containers that aggregate information about the items
 
 # Products
 
-With **PIM**, [[= product_name =]] handles products offered in the website, 
-including their specifications, attributes, assets, variants and pricing.
-
-PIM's features are available from the left menu.
-
-![PIM in the menu](img/catalog_menu.png "PIM in the menu")
-
-To create a product you must first decide which product type it belongs to.
-
-## Product types
-
-Product types are templates that contain a combination of [Fields](../content_management/content_model.md#fields-and-field-types) and [attributes](#attributes) which constitute a product definition.
-By default, each product type contains such Fields as name, specification, image or category, but you can change it as required.
-You need different product types, because products of type "Laptops" contain different Fields and attributes than those of type "White appliances".
-
-When you create a new product type, you can choose between two available product type flavors: Physical and Virtual:
-
-- Physical - tangible products.
-They can use measurement attributes. They require shipment in the online purchase process.
-Examples: heaters, laptops, phones.
-- Virtual - non-tangible items. They can be sold individually, or as part of a product bundle.
-They don't require shipment in the online process. Examples: memberships, services, warranties. 
-
-A product type also defines both the attributes and VAT rates for all its products.
-
-When a product type is created, you can review its fields, attributes, and VAT rate settings on the product type's details screen, without having to open it for editing.
-
-![VAT rates in product type's details view](img/vat_rates_product_details.png "VAT rates in product type's details view")
-
-If your [user Role](../permission_management/work_with_permissions.md) has the `ProductType/Edit` 
-permission, you can [modify product types and add individual attributes or attribute groups](create_product_types.md).
-
-### Attributes
-
-Attributes describe product characteristics.
-Customers can use them to filter and search for products.
-Attribute types define what kind of information you can store in an attribute.
-Typical product attribute examples include dimensions, weight, color, or format.
-
-For more information, see [Work with product attributes](work_with_product_attributes.md).
-
-## Products
-
-Products are instances of a particular product type.
+Products are instances of a particular [product type](product_types.md).
 A product is an object that's based on a product type template.
-Products can have variants that you build around attributes.
-They can be categorized and organized into catalogs.
+It can have [variants](work_with_product_variants.md) that you build around [attributes](work_with_product_attributes.md).
+Products can be put in [catalogs](work_with_catalogs.md) and organized into [categories](work_with_product_categories.md).
 
-Also, for each product and product variant, you can define its availability, stock and price.
+For each product and product variant, you can define its [availability](manage_availability_and_stock.md), stock and [prices](manage_prices.md).
+
+When you create or edit products, you can add [assets](work_with_product_assets.md) in a form of images.
+Assets can be assigned to the base product, and to one or more of its variants.
 
 For more information about creating products, see [Create product](create_edit_product.md#create-and-edit-products).
 
-### Product assets
+### Product completeness
 
-When you create or edit products, you can add assets in a form of images.
-Assets [can be assigned](work_with_product_assets.md) to the base product, and to one or more of its variants.
+Before your customers can purchase products, the website [administrator must configure]([[= user_doc =]]/pim/enable_purchasing_products/) at least one region and one currency for the shop, and VAT rates for each of the regions.
+You must then set:
 
-### Product completeness
+- VAT rates for the product type
+- at least one price for the product
+- availability with positive or infinite stock for the product
 
-When you create or edit a product, under the product name, you can see visual indication
-of what part of product information (tasks) you have completed, and what part is still missing.
+When you create or edit a product, under the product name, you can see a progress bar with an approximate indication
+of how much of the product information you provided, and how much is still missing.
 
 ![Quick view of product completeness](img/product_completeness_bar.png "Quick view of product completeness")
 
-Here you can see full information about completed tasks in the product view's **Completeness** tab.
-
-This tab lists all tasks required for product configuration, including:
+To find out in detail, which pieces of product information require your attention, go to the product view's **Completeness** tab.
+It lists all tasks required for product configuration, including:
 
 - content (such as images and descriptions)
 - attributes
@@ -83,46 +44,5 @@ This tab lists all tasks required for product configuration, including:
 ![Product completeness screen](img/product_completeness.png "Product completeness screen")
 
 You can click the edit button next to an unfinished task in the Completeness table
-to move directly to the screen where you can add the missing information.
-
-
-## Product categories
-
-With product categories you can organize products within PIM and create relationships between them. 
-One of the reasons for applying product categories is assisting users in searching for products.
-
-Each category can be assigned to multiple products, and each product can belong to multiple categories of different or similar character, for example:
-
-- Business Laptops
-- Windows OS Devices
-- Stock clearance
-
-You can enable the use of product categories, assign products to categories and vice versa, and [define your own categories](work_with_product_categories.md).
-
-## Product variants
-
-Product variants enable you to have multiple versions of one product, differing in some characteristics.
-
-Typical examples are a t-shirt in different colors, or a laptop with different hard disk sizes.
-
-You can [create variants based on product attributes](work_with_product_variants.md).
-
-## Product prices
-
- You can [set a base price and custom prices](manage_prices.md) for the product and for its variants.
- Prices can differ depending on [customer group](../customer_management/manage_customers.md) and [currency](../pim/manage_currencies.md) and be applied according to the rules.
-
-## Product availability and stock
-
-You can [control a product's availability](manage_availability_and_stock.md), which translates into 
-whether it's being offered for purchase, and the available stock.
-You can either set the exact number of product pieces available in stock or indicate 
-that availability is infinite, for example, for digital, downloadable products. 
-
-## Product catalogs
-
-You can [create special catalogs](work_with_catalogs.md), for example, to differentiate the offering 
-that's presented to B2B and B2C users, retailers and distributors or different regions.
-Catalogs contain a sub-set of products from the system.
+to go directly to the screen where you can add the missing information.
 
-![Catalog menu with a sample catalog](img/catalog.png "Catalog menu with a sample catalog")

docs/pim/work_with_catalogs.md

@@ -5,8 +5,15 @@ description: Catalogs allow creating filtered product lists for special purposes
 
 # Work with catalogs
 
-With [catalogs](products.md#product-catalogs) you can create product lists for special purposes, for example, 
-for B2B and B2C uses, for retailers and distributors or for different regions.
+You can create special catalogs, for example, to differentiate the offering 
+that's presented to B2B and B2C users, retailers and distributors or different regions.
+
+## Catalogs
+
+Catalogs are collections of products selected by using configurable filters.
+They are specific to each of your websites or storefronts, which means that they contain products that are presented or sold in a specific website.
+
+![Catalog menu with a sample catalog](img/catalog.png "Catalog menu with a sample catalog")
 
 ## Create catalogs
 

docs/pim/work_with_product_assets.md

@@ -4,7 +4,8 @@ description: Add image assets to products or product variants.
 
 # Work with product assets
 
-You can add image assets to products or product variants.
+When you [create or edit products](create_edit_product.md), you can add assets in a form of images. 
+Assets can be assigned to the base product, and to one or more of its [variants](work_with_product_variants.md).
 
 To add assets to a product, in the product's **Assets** tab browse or drag and 
 drop image files from disk, or select an existing image asset from library.

docs/pim/work_with_product_categories.md

@@ -1,13 +1,26 @@
 ---
-description: You can create a structure of tags that can be assigned to products to help categorize products, to assist users in searching. You create, manage and assign categories manually.
+description: You can create a structure of tags that can be assigned to products to help categorize products, to assist visitors in searching. You create, manage and assign categories manually.
 ---
 
 # Work with product categories
 
-[Product categories](products.md#product-categories) are organized into a Category tree, which you can access from the **Product catalog** panel. The **Categories** screen is where you manually create a hierarchy of categories and manage category entries. 
+[Product](products.md) categories are organized into a Category tree, which you can access from the **Product catalog** panel. The **Categories** screen is where you manually create a hierarchy of categories and manage category entries. 
 
 ![Product category tree](img/product_categories.png "Product category tree")
 
+## Product categories
+
+With product categories you can organize products within PIM and create relationships between them.
+One of the reasons for applying product categories is assisting visitors in searching for products.
+
+Each category can be assigned to multiple products, and each product can belong to multiple categories of different or similar character, for example:
+
+- Business Laptops
+- Windows OS Devices
+- Stock clearance
+
+You can enable the use of product categories, assign products to categories and vice versa, and define your own categories.
+
 ## Enable product categories
 
 Before you can assign categories to products, make sure that the **Taxonomy Entry Assignment** field is added and set as required in all the [product types](products.md#product-types) that define products from PIM which you want to categorize. 

docs/pim/work_with_product_variants.md

@@ -4,6 +4,9 @@ description: Create multiple variants of one product, based on attributes such a
 
 # Work with product variants
 
+With product variants you can have multiple versions of one product, differing in some characteristics.
+Typical examples would be a t-shirt in different sizes and colors, or the same model of laptop with different hard disk sizes.
+
 To use an [attribute](products.md#attributes) to create [variants](products.md#product-variants), mark the attribute as **Used for product variants** when you create a [product type](create_product_types.md).
 
 ![Product type definition with attributes used for variants](img/product_type_attr_used_for_variants.png "Product type definition with attributes used for variants")

mkdocs.yml

@@ -75,18 +75,22 @@ nav:
         - Work with payments: commerce/payment/work_with_payments.md
         - Work with payment methods: commerce/payment/work_with_payment_methods.md 
     - PIM:
-        - Product Information Management: pim/products.md
-        - Create product types: pim/create_product_types.md
-        - Work with product attributes: pim/work_with_product_attributes.md
-        - Create and edit products: pim/create_edit_product.md
-        - Create virtual products: pim/create_virtual_product.md
-        - Work with product assets: pim/work_with_product_assets.md
-        - Work with product categories: pim/work_with_product_categories.md
-        - Work with product variants: pim/work_with_product_variants.md
-        - Work with product prices: pim/manage_prices.md
-        - Work with product availability and stock: pim/manage_availability_and_stock.md
+        - Product Information Management: pim/pim.md
+        - PIM settings:
+            - Product types: pim/product_types.md
+            - Create product types: pim/create_product_types.md
+            - Work with product attributes: pim/work_with_product_attributes.md
+            - Work with currencies: pim/manage_currencies.md
+        - Products:
+            - Products: pim/products.md
+            - Create and edit products: pim/create_edit_product.md
+            - Create virtual products: pim/create_virtual_product.md
+            - Work with product assets: pim/work_with_product_assets.md
+            - Work with product variants: pim/work_with_product_variants.md
+            - Work with product prices: pim/manage_prices.md
+            - Work with product availability and stock: pim/manage_availability_and_stock.md
         - Work with catalogs: pim/work_with_catalogs.md
-        - Work with currencies: pim/manage_currencies.md
+        - Work with product categories: pim/work_with_product_categories.md
         - Work with product page URLs: pim/work_with_product_page_urls.md
     - Customer management:
         - Customer Portal: customer_management/customer_portal.md