[Request]: Document mapping of integration variable types to EUI fields, other Fleet/Integrations UI concerns

kpollich commented 2 months ago

Description

Fleet is responsible for generating a "policy editor" from integration manifests that allows for user input on integration policies. As part of this process, Fleet essentially translates the integration's various manifest.yml file into a dynamic EuiForm component that allows user input for all the integration's defined variables.

Today, we don't really have this process documented, and integration maintainers aren't necessarily familiar enough with EUI to make proper decisions about which variable type to use, what type of content to include for help text, labels, descriptions, etc. We should close this gap.

Resources

Fleet dev docs that touch on this a bit

Which documentation set does this change impact?

Integrations

Feature differences

N/A

What release is this request related to?

N/A

Collaboration model

The engineering team

Point of contact.

Main contact: @kpollich

Stakeholders: @elastic/ecosystem

jsoriano commented 2 months ago

Does it come from some request? Do we have more context? I wouldn't like to couple so much variables declaration to how they are represented in Kibana.

integration maintainers aren't necessarily familiar enough with EUI

I kind of think this is a feature :slightly_smiling_face:

Package developers shouldn't need to be aware of the final representation of the variables, they should worry only about properly declaring the variables they need, with the kind of data they expect, and ideally some information/description for users. In the same way, the package spec should not be specific about the UI widgets used to represent each variable.

We also have to take into account that there can be multiple interfaces, we currently have two, one based on EUI, and the other one being the API. We could have more in the future, and package development should be kept on a declarative side, without having to think about how variables are exposed to users.

I think though we can check that we are good in the following areas depending on the target audience:

For package/integration developers, be sure that it is clear how to declare variables. Provide recommendations for title, description and type. And not only variables, there are probably other areas of the spec that could be better documented. It'd be also nice to have better reference docs (maybe based on https://github.com/elastic/package-spec/issues/400).
For Kibana/Fleet developers, we can indeed provide guidelines about how to represent variables as EUI fields.

kpollich commented 2 months ago

Package developers shouldn't need to be aware of the final representation of the variables, they should worry only about properly declaring the variables they need, with the kind of data they expect, and ideally some information/description for users. In the same way, the package spec should not be specific about the UI widgets used to represent each variable.

At the very least we need package maintainers to be somewhat aware of the presentational guidelines associated with these values surfacing in a UI, e.g. https://eui.elastic.co/#/forms/form-layouts/guidelines.

For example, keeping the description of a form field under a certain length so that it doesn't disrupt the overall form layout is important. Using help text for validation purposes vs using placeholders for instructions is also quite important, and disregarding these guidelines can result in a degraded experience for users who rely on screen readers especially. Because we consume a form library to generate this UI, we need to somehow capture the expectations and guidelines for that form library in the package spec.

I agree that this a tight coupling here, or expecting package maintainers to also be UX engineers is not viable. However, perhaps we can align the package spec closer to the recommendations set forth by EUI to make this easier to handle for maintainers.

We also have to take into account that there can be multiple interfaces, we currently have two, one based on EUI, and the other one being the API. We could have more in the future

I don't know how likely it is we'll have another UI representation in the future that uses something other than EUI, but it is technically possible for someone to build a UI that doesn't rely on EUI. I do think trying to capture these kinds of constraints or guidelines in a declarative fashion without requiring specifically EUI knowledge of package maintainers is a good idea.

jsoriano commented 2 months ago

perhaps we can align the package spec closer to the recommendations set forth by EUI to make this easier to handle for maintainers.

Yes, I would prefer to go in this direction, maybe we can revisit the affected attributes. It can make totally sense to set a length limit in title and description, and maybe we can add another field for reference documentation for variables that need more content.

Adding restrictions through the spec also has the advantage that they are more difficult to ignore than guidelines in the docs. Actually, checking the description of the description attribute, it already mentions that it should be "short", what is likely being ignored in some cases.

Using help text for validation purposes vs using placeholders for instructions is also quite important

What does this refer to? Do you have an example?

elastic / observability-docs