Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Connector help rework #4082

Open
wants to merge 9 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
97 changes: 67 additions & 30 deletions develop/devguide/Connector/ConnectorHelp/Connector_help_pages.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This more or less in line with https://docs.dataminer.services/user-guide/Cloud_Platform/Catalog/Best_Practices_When_Documenting_Catalog_Items.html.
Can we not simply make a reference to these guidelines?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since there are some differences, it depends on whether you want to bring the connector pages fully in line with those for other Catalog items. If yes, we can largely replace this text with a reference and just add that a link must be added to the technical page. Otherwise, I could also add a tip referring to the best practices page for general best practices (e.g. the use of visuals).


#### 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.). Avoid technical explanations here. Keep things high-level and user-centric.

#### Key Features

List up the main features of the connector. There is no need to list up all features here; just the main ones is sufficient. We typically aim at a list of 3 to 5 features.

#### Use Cases

This section is optional. Sometimes it will make sense to add some specific use cases on top of the above Key Features section, but sometimes it will be better to leave out this Use Cases section to avoid duplicate info.

#### Technical info

This section can be used to list up prerequisites or any other important technical info that is important enough to mention on this main page. However, you should keep this section to the absolute minimum. Any other technical details do not belong here but should be added on 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:

Expand All @@ -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:

Expand All @@ -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.

Expand All @@ -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.

Expand All @@ -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.

Expand Down
Original file line number Diff line number Diff line change
@@ -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).
Original file line number Diff line number Diff line change
@@ -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.]

Expand Down
7 changes: 5 additions & 2 deletions develop/toc.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading