search

syndesisio / syndesis-ui

The front end application or UI for Syndesis - a flexible, customizable, cloud-hosted platform that provides core integration capabilities as a service. It leverages Red Hat's existing product architecture using OpenShift Online/Dedicated and Fuse Integration Services.
https://syndesis.io/
14 stars 28 forks source link

Apply Red Hat style conventions to UI text labels and descriptions #187

Closed TovaCohen closed 7 years ago

TovaCohen commented 7 years ago

Red Hat style conventions should be followed in the iPaaS UI. For example, the sprint 8 demo shows the Salesforce Upsert Contact connection page with these fields:

Login Url Client Id Client Secret Refresh Token

"URL" and "ID" should always be all caps.

Would a citizen user know what a Salesforce Client Secret is? what a Refresh Token is? Maybe a description line is planned for each field. And perhaps we can help write clear configuration field descriptions that appear in the UI.

gashcrumb commented 7 years ago

I think when we generate the forms we can probably pass labels through a filter to massage things like url and id to be all caps. I think we kinda need to do this anyway to properly title-ize all the form labels.

We do set the description on the form, it's driven by the data from the underlying connector. Also the expert user would be creating the connection and picking what fields would be exposed to the citizen user, so hopefully stuff like 'refresh token' and 'client secret' would be kinda filled in by the expert user already. Hopefully :-)

kahboom commented 7 years ago

@gashcrumb +1

gashcrumb commented 7 years ago

So I agree here, but this issue is to coarse/open ended. This needs to be broken out into more specific units of work either by creating an issue per page or at least an issue by functional area (integrations, connections, settings etc). @TovaCohen when you get a chance would you be able to do this?

Once that's done we should close this issue.

TovaCohen commented 7 years ago

@fbolton do you have a suggestion for the best way to accomplish this work? I hesitate to create separate epics for this kind of doc work because I think that improving any text in the UI should be closely coupled with the work of implementing the UI. For UI work to be done, I am wondering if each epic that adds to the UI should have a doc task. For UI already in place, I guess we need an epic for each page or each functional area as Stan suggests.

fbolton commented 7 years ago

@TovaCohen I think you have the right idea. Perhaps an epic for each functional area, for UI already in place (so it is not too fine-grained)? From the docs perspective, the resolution of this issue would be a new process for giving feedback on the UI and tracking this work in GitHub/ZenHub.

TovaCohen commented 7 years ago

I'm going to close this without creating other issues. I'm not certain about the most efficient way to make all the text in the UI comply with Red Hat style standards. But accomplishing this is not something I will forget about. When I get back to actively working on Syndesis user doc, we'll figure out what the process should be and create issues as needed.