Syndesis: Connectors - provide sufficient information for both name and description when defining a connector

[dongniwang]

This is a...

[x ] Feature request
[ ] Regression (a behavior that used to work and stopped working in a new release)
[ ] Bug report  
[ ] Documentation issue or request

Description

Ran into the issue of not having a descriptive description for some of the connection actions as part of the discussion https://github.com/syndesisio/syndesis-react/pull/418.

Having the description repeats the action name makes it feel like a bug from a user experience point of view (see screenshot below).

Can we strive to supply a more descriptive description when defining a connector? I'd happy to review any of those texts and I know @TovaCohen would be happy to help as well if writing is a concern.

[gashcrumb]

This needs to be done in the connector definition files.

[gashcrumb]

Also we should call out the particular connectors, otherwise nothing is going to happen on this issue. It was prompted by the built-in Timer connection, as it has the same text for both the name and description.

[dongniwang]

Yeah, the first step should probably be checking the out-of-the-box connectors as those are the first point of contact for users.

[dongniwang]

@heiko-braun I think this is not just a uxd issue. Can we get someone from the backend team to take a look at this, please? Thank you!

[TovaCohen]

For Timer, do these descriptions meet the need:
Simple Timer: Specify a period and its time unit.
Cron Timer: Specify a cron utility expression.

If yes, I can submit a PR for this now. I updated the timer.json file.

It's been on my list to look at all the connectior.json files and improve the descriptions and make them consistent. I'll take this on if that's okay with all of you.

[gashcrumb]

@TovaCohen that'd be perfect, thanks!

[zregvart]

I think we can do better on the names as well, I don't think we need to repeat _Trigger_, something like:

Simple: Periodically trigger by specifying period and its time unit.
Cron: Specify cron utility expression for more complex triggers.

Or thereabouts.

[TovaCohen]

For Timer, I'd also like to change the connection description from:
"Trigger events based on an interval or a cron expression
to
Trigger execution of an integration based on an interval or a cron expression.
I'll do that unless I hear otherwise.
Do I do that in
app/server/dao/src/main/resources/io/syndesis/server/dao/deployment.json ?
Should I do these changes in syndesis-react?

Zoran, yes, good idea to not repeat "Timer". How's this:

Simple: Specify an amount of time and its unit to periodically trigger integration execution.
Cron : Specify a cron utility expression for a more complex integration execution schedule.

[dongniwang]

Thank you so much @TovaCohen and @zregvart ! Appreciate your feedback and input!

[TovaCohen]

I'm going to look at the json file for one connector each day.
I''ll update the field labels to consistently uppercase only the first letter.
I'll ensure that labels are helpful and correct.
So I'll keep this open, and commit with this issue number.

[avano]

it looks ok for all connectors except mongo:

cat mongodb/src/main/resources/META-INF/syndesis/connector/mongodb3.json | jq '.actions[].description'
"Mongo DB producer"
"Mongo DB consumer"

[TovaCohen]

@avano I'm working on the user doc for the MongoDB connector this week. When I have a better understanding of what it is doing, I'll suggest better action names, probably something like Read, Write, or maybe Get, Update.
I think there are other connectors that could use some improvement in the text of their UIs, and I'll also work on that. But after two weeks of PTO, so that will be in late August. I'd like to keep this open to log the improvements and remind me to do it.

[stale[bot]]

This issue has been automatically marked as stale because it has not had any activity since 90 days. It will be closed if no further activity occurs within 7 days. Thank you for your contributions!