Connector help rework

develop/devguide/Connector/ConnectorHelp/Connector_help_pages.md

@@ -4,37 +4,46 @@ uid: Connector_help_pages
 
 # Connector documentation
 
-For every connector that is developed for DataMiner, a corresponding page should be available in the connector documentation. This "connector help" page details among others how the connections should be set up when you create an element with the connector, how the element should be used, etc. If a connector exports child connectors, a page should also be created for each of these child connectors.
+For every connector that is developed for DataMiner, 2 or more documentation pages should be made.
 
-When you develop a connector using DIS, you can generate the connector documentation with the *Plugins* > *Generate driver help* option in the [DIS menu](xref:DIS_menu). You can also create the page directly in Markdown, starting from our [template](xref:Connector_help_template). When you have created the page, add it in the [dataminer-docs-connectors](https://github.com/SkylineCommunications/dataminer-docs-connectors) repository.
+The first one, which we will call the [marketing page](#Marketing-page), should be appealing and focus on demonstrating the value the connector can bring to users. Comparing our Catalog to a real physical store, see this page as being the packaging of your product.
 
-## Adding a new connector documentation page
+The second one, which we will call the [technical page](#Technical-page), should be a subpage of the marketing one and contain further technical details. Comparing our Catalog to a real physical store again, see this page as being the technical notice of your product. This technical page details among others how the connections should be set up when you create an element with the connector, how the element should be used, etc. If a connector exports child connectors, a subpage should also be created for each of these child connectors.
 
-### File name and folder
+When you develop a connector using DIS, you can pre-generate the connector documentation pages with the *Plugins* > *Generate driver help* option in the [DIS menu](xref:DIS_menu). You can also create the pages directly in Markdown, starting from our [marketing](xref:Connector_marketing_template) and [technical](xref:Connector_technical_template) templates. When you have created the pages, add them in the [dataminer-docs-connectors](https://github.com/SkylineCommunications/dataminer-docs-connectors) repository.
 
-To make sure your page can be automatically included in the [DataMiner Catalog](https://catalog.dataminer.services/), it is important that you use the correct file name and place the file in the correct folder:
+## Adding new connector documentation pages
 
-- Make sure the **file name** is the **exact name of the connector in the Catalog**, but with **underscores instead of spaces**. For example, the file name of the *Microsoft Platform* documentation page has to be *Microsoft_Platform.md*. Make sure the casing is the same, and do not replace any other characters with underscores. Any mismatch between the file name and the connector name will make the documentation **unavailable** in the Catalog.
+### File names and folder
+
+To make sure your pages can be automatically included in the [DataMiner Catalog](https://catalog.dataminer.services/), it is important that you use the correct file names and place the files in the correct folder:
+
+- Marketing page: make sure the **file name** of your marketing page is the **exact name of the connector in the Catalog**, but with **underscores instead of spaces**. For example, the file name of the *Microsoft Platform* marketing page has to be *Microsoft_Platform.md*. Make sure the casing is the same, and do not replace any other characters with underscores. Any mismatch between the file name and the connector name will make the documentation **unavailable** in the Catalog.
 
   > [!IMPORTANT]
   > It is very important that the file name **does not contain any spaces**. If the file name contains spaces, this will cause an error when the new file is pushed to the DataMiner Catalog.
 
-- Add your documentation file in the following folder of the [dataminer-docs-connectors](https://github.com/SkylineCommunications/dataminer-docs-connectors) repository: */dataminer-docs-connectors/connector/doc*
+- Technical page: make sure the **file name** follows the same rules as mentioned here above for the Marketing page followed by a **_Technical** prefix. For example, the file name of the *Microsoft Platform* technical page has to be *Microsoft_Platform_Technical.md*.
+
+- Add your documentation files in the following folder of the [dataminer-docs-connectors](https://github.com/SkylineCommunications/dataminer-docs-connectors) repository: */dataminer-docs-connectors/connector/doc*
 
 ### Table of contents
 
-When you add a new page to the connector documentation, you will need to add it to the table of contents as well. To do so, add it to the *toc.yml* file in the *connector* folder. Please note:
+When you add new pages to the connector documentation, you will need to add them to the table of contents as well. To do so, add it to the *toc.yml* file in the *connector* folder. Please note:
 
-- The connector documentation pages are listed in alphabetical order underneath each vendor node. Make sure to add your page in the correct location.
-- Use the following syntax to add the page:
+- The connector documentation pages are listed in alphabetical order underneath each vendor node. Make sure to add your pages in the correct location.
+- Use the following syntax to add the pages:
 
   ```yml
-    - name: Connector name
-      topicUid: Connector_help_Connector_name
+  - name: Connector name
+    topicUid: Connector_help_Connector_name
+    items:
+      - name: Connector name Technical
+        topicUid: Connector_help_Connector_name_Technical
   ```
 
 > [!TIP]
-> The value you need to specify next to "topicUid:" is a UID that should be specified at the top of the markdown file. See [Adding a page](xref:CTB_Adding_New_Page).
+> The value you need to specify next to "topicUid:" is a UID that should be specified at the top of the markdown files. See [Adding a page](xref:CTB_Adding_New_Page).
 
 > [!NOTE]
 > If you do not configure the table of contents correctly, the automatic checks that run after you submit your pull request will fail. You can then click *Details* to find out what exactly went wrong.
@@ -51,33 +60,61 @@ Use DocFX Flavored Markdown (DFM). See [Markdown syntax](xref:CTB_Markdown_Synta
 
 ### Title
 
-The title of the page should be the name of the connector in the [DataMiner Catalog](https://catalog.dataminer.services/).
+The title of both pages should be the name of the connector in the [DataMiner Catalog](https://catalog.dataminer.services/).
+
+### Marketing page
+
+#### About
+
+In this about section, add a short paragraph explaining the **function of the connector**. Try to also include some **information about the data source**. If you copy this information from somewhere else, make sure it fits the informative context of documentation (e.g. remove meaningless praise like "best-of-breed", "top-of-the-line", etc.). Don't be too technical here. Keep things high level and user centric.
+
+#### Key Features
+
+List up the main features of the connector. No need to list up all features here, stick to the main ones, we typically aim at a list of 3 to 5 features.
+
+#### Use Cases
+
+This section is optional. Some times it will make sense to add some specific use-cases on top of the above Key Features section. Some times it will be skipped to avoid duplicating info already available in the above Key Features section.
+
+#### Technical info
+
+This section can be use to list up prerequisites or any other important technical info that you deem necessary to put on this main page. Keep this section to the absolute minimum though. Any other technical detail does not belong here but will go to the [technical page](#Technical-page).
+
+Add a note containing a link to the connector [technical page](#Technical-page).
+
+```md
+> [!NOTE]
+> For detailed technical information, refer to our [technical documentation](xref:Connector_help_My_connector_name_Technical).
+
+```
+
+### Technical page
 
-### Introduction paragraph
+#### Introduction paragraph
 
 In the **first paragraph** below the title, add a short paragraph explaining the **function of the connector**. Try to also include some **information about the data source**. If you copy this information from somewhere else, make sure it fits the informative context of documentation (e.g. remove meaningless praise like "best-of-breed", "top-of-the-line", etc.).
 
-### 'About' section
+#### 'About' section
 
 **OBSOLETE**
 
 Older connector documentation will contain an *About* section with tables with version info, product info, and system info, but this is no longer required as this information is now included directly within the protocol.xml via the various [VersionHistory](xref:Protocol.VersionHistory) tags.
 
-### 'Configuration' section
+#### 'Configuration' section
 
 In the **Configuration** section, add the information needed to create a DataMiner element with the connector. This section will need to have one or more subsections, depending on the connector. You can find more information about these below.
 
 > [!NOTE]
 > For an exported child connector, it is usually sufficient to mention that it is automatically exported by the parent connector (with a link to the parent connector and mention of the version exporting the child connector, if relevant).
 
-#### 'Connections' subsection
+##### 'Connections' subsection
 
 Except for exported child connectors, every connector documentation page should have a **Connections** subsection. For each connection, you should add a title mentioning the name of the connection as defined in the connector, e.g. "SNMP Connection – Trap Input". For the Main connection, use "Main" as the name of the connection.
 
 Below are a couple of examples of such connections sections.
 
 ```md
-#### SNMP Connection - Main
+##### SNMP Connection - Main
 
 This connector uses a Simple Network Management Protocol (SNMP) connection and requires the following input during element creation:
 
@@ -94,7 +131,7 @@ SNMP Settings:
 ```
 
 ```md
-#### HTTP Connection - Main
+##### HTTP Connection - Main
 
 This connector uses an HTTP connection and requires the following input during element creation:
 
@@ -106,31 +143,31 @@ HTTP CONNECTION:
 ```
 
 ```md
-#### Virtual Connection - Main
+##### Virtual Connection - Main
 
 This connector uses a virtual connection and does not require any input during element creation.
 ```
 
 > [!TIP]
-> You can find the structure for all possible connection sections in the [template](xref:Connector_help_template). If you copy from there, remember to remove the placeholder text and the square brackets surrounding it.
+> You can find the structure for all possible connection sections in the [technical template](xref:Connector_technical_template). If you copy from there, remember to remove the placeholder text and the square brackets surrounding it.
 
-#### 'Initialization' subsection
+##### 'Initialization' subsection
 
 If, once the element has been created, the connector requires more actions from the user before it can actually be used, you will need to add an **Initialization** section that explains what needs to be done. This could for example be configuring parameters for authentication. Make sure it is clear to the user what they need to fill in and where.
 
-#### 'Web Interface' subsection
+##### 'Web Interface' subsection
 
 If there is a Web Interface page, always add a **Web Interface** subsection, containing the remark: "The web interface is only accessible when the client machine has network access to the product."
 
-#### 'Redundancy' subsection
+##### 'Redundancy' subsection
 
 If redundancy is defined in the connector, add a **Redundancy** subsection that explains how this should be configured.
 
-#### Other configuration subsections
+##### Other configuration subsections
 
 Depending on the connector, other subsections may be needed, e.g. in case Automation scripts, Correlation rules, Visio files, etc. need to be configured. You can find a number of possible subsections listed in the template. However, this list is not exclusive; you can add different configuration subsections if this makes sense for your connector.
 
-### 'How to Use' section
+#### 'How to Use' section
 
 The **How to Use** section of your page is where you explain what users can actually do with the connector, and especially how they can do it.
 
@@ -152,7 +189,7 @@ For a very simple one-page connector, it can be sufficient to specify something
 
 If you need to add more than just a couple of lines of text because the connector is quite complicated or you need to go into a lot of detail for some of the features, use subheaders to keep the page easy to scan for the reader. These subheaders can either reflect the different pages you want to discuss, or the different topics, e.g. General Settings, Import and Export, Logging.
 
-### 'DataMiner Connectivity Framework' section
+#### 'DataMiner Connectivity Framework' section
 
 For a connector that supports DCF, add information on which connector range supports DCF, and from which version of DataMiner it can be used. If you start from the template, remember to replace the placeholder text and remove the square brackets surrounding it.
 
@@ -162,9 +199,9 @@ For a page for a parent DVE element, to make it clear that DCF in a child DVE is
 
 For a DVE child element, no detailed description is necessary in this section. Instead it is sufficient to mention the following: "Connectivity for this connector is managed by the parent connector [connector name]."
 
-If applicable, add the **Interfaces** and/or **DCF Connections** sections as detailed in the [template](xref:Connector_help_template).
+If applicable, add the **Interfaces** and/or **DCF Connections** sections as detailed in the [technical template](xref:Connector_technical_template).
 
-### 'Notes' section
+#### 'Notes' section
 
 If you want to add information about the connector that does not fit under any of the other sections, add a **Notes** section for this. This section can also have subsections if it contains a lot of information.
 

develop/devguide/Connector/ConnectorHelp/Connector_marketing_template.md

@@ -0,0 +1,60 @@
+---
+uid: Connector_marketing_template
+---
+
+# Connector marketing documentation template
+
+## About
+
+[Short description of the data source and of the function of the connector.]
+
+## Key Features
+
+- **Feature 1 name**: small description of feature 1.
+
+- **Feature 2 name**: small description of feature 2.
+
+- **Feature 3 name**: small description of feature 3.
+
+- **Feature 4 name**: small description of feature 4.
+
+- **Feature 5 name**: small description of feature 5.
+
+## Use Cases
+
+### Use Cases 1
+
+**Challenge**: challenge description.
+
+**Solution**: solution description.
+
+**Benefit**: benefit(s) description.
+
+### Use Cases 2
+
+**Challenge**: challenge description.
+
+**Solution**: solution description.
+
+**Benefit**: benefit(s) description.
+
+### Use Cases 3
+
+**Challenge**: challenge description.
+
+**Solution**: solution description.
+
+**Benefit**: benefit(s) description.
+
+## Technical info
+
+### Prerequisites
+
+- **Prerequisite 1** is needed for...
+
+- **Prerequisite 2** are needed for...
+
+- **Prerequisite 3** is required for...
+
+> [!NOTE]
+> For detailed technical information, refer to our [technical documentation](xref:Connector_help_My_connector_name_Technical).

develop/devguide/Connector/ConnectorHelp/Connector_help_template.md → develop/devguide/Connector/ConnectorHelp/Connector_technical_template.md

@@ -1,8 +1,8 @@
 ---
-uid: Connector_help_template
+uid: Connector_technical_template
 ---
 
-# Connector documentation template
+# Connector technical documentation template
 
 [Short description of the data source and of the function of the connector.]
 

develop/toc.yml

@@ -620,8 +620,11 @@ items:
     - name: Connector documentation
       topicUid: Connector_help_pages
       items:
-      - name: Connector documentation template
-        topicUid: Connector_help_template
+      - name: Connector marketing documentation template
+        topicUid: Connector_marketing_template
+        items:
+        - name: Connector technical documentation template
+          topicUid: Connector_technical_template
     - name: Questions & Answers
       topicUid: QuestionsAndAnswers
     - name: Best practices