Improve Connectors documentation for new users

[alexronquillo]

As a reader who is inexperienced with connectors, I found many issues with our documentation. Here are some notes, but I would recommend a full edit of these docs.

Connectors

• An overview page about connectors should explain the concept of connectors. The language here focuses on "built-in" connectors.
• The introduction states "Connectors are often configured as a BPMN process task". If it's "often" configured this way, when is it not?

How to use connectors

• "How to use connectors" should explain how to use connectors, starting from the basics. The first explanation here is about secrets.
• "Find available connectors in out-of-the-box connectors." We use built-in connectors and out-of-the-box connectors interchangeably. We should unify these terms.
• "Learn how to install connectors in Self-Managed." This links to the connectors overview in Self-Managed, which doesn't explain how to "install" connectors.

Integrate a built-in connector

• "Review our introduction to connectors to get familiar with their capabilities." It's a stretch to say the concept introduction teaches the capabilities of connectors--it's pretty brief.
• This user guide is confused about whether it does or doesn't want to introduce the concept of connectors. It should delegate that task to an introductory explainer and focus on the instruction.
• "Set up". This section should really be titled "Prerequisites" or, at least "Setup".
• "We'll implement our connector with Modeler. To get started, ensure you’ve created a Camunda 8 account." We should decide whether our guides target SaaS users or Self-Managed users.
• "You'll also need to create a SendGrid account if you don't have one already". This is an introductory guide. We should choose a connector with as few dependencies as possible to reduce friction.
• "Create a cluster" Do we need to repeat these instructions here? There is already a guide for that.
• This reads more like a tutorial than a user guide. Therefore, "In this example, we've designed the following BPMN diagram" should include a downloadable BPMN file so the user can import the contents.
• "Camunda offers a variety of available connectors." In a tutorial that uses a specific story and connectors, this breaks up the rhythm and directs the reader's attention away.
• "Click the Append connector item in the panel." I don't see this item. Is this from an old design?
• "To send an email via SendGrid, for example" For example sounds like we're giving the reader options. We should either be more general with the whole piece (user guide) or more specific (tutorial).
• "To add our productivity applications connector, take the following steps:" We need to explain the user must perform these steps in Implement mode or the properties we refer to aren't available. This may be confusing.

Microsoft Teams connector

• "From the canvas: Select an element and click the Change element icon to change an existing element, or use the append feature to add a new element to the diagram." We should be more specific about what options the user needs to click.
• "From the properties panel: Navigate to the Template section and click Select." This is only available in properties for some elements. Start event, which is used in the screenshot, is not one of them.
• Nothing about the section titled "Create a Microsoft Teams connector task" specifies anything about the Microsoft Teams connector. This should probably be moved elsewhere more general or, at least, renamed.