You are viewing a plain text version of this content. The canonical link for it is here.

Posted to dev@texera.apache.org by "Neilk1021 (via GitHub)" <gi...@apache.org> on 2026/07/22 19:00:01 UTC

[D] UX Feedback (Operator Descriptions) [texera]

GitHub user Neilk1021 created a discussion: UX Feedback (Operator Descriptions)

Currently a lot of the operators suffer form "if you know, you know" syndrome. While it may be hard to rewrite descriptions for 150 operators, it might be worthwhile to improve a few of the most used ones.

A lot of operators might *feel* self explanatory, but many obfuscate needed details about how they work, which may lead to user frustration. Take for example the Text Input source. It output's text, sure, but the mechanism for how it does that and what exactly it returns is completely obfuscated. Now as developer we might have the instinct that this is where docs or tutorial videos comes in, but Texera is a User facing product and having to go outside of Texera ruins the workflow.

I don't want to hammer in the sins of this operator too hard, as it's mainly to illustrate a broader point. I think a lot of operators currently fall into this trap and I want to go through to improve their descriptions a bit. A good example of an operator implemented well is the various hugging face operators as a lot of their functionality is self documenting.

In terms of actual questions, I'd like to know what operators developers don't currently know how to use, or operators they remember being hard to use at first.

GitHub link: https://github.com/apache/texera/discussions/6798

----
This is an automatically sent email for dev@texera.apache.org.
To unsubscribe, please send an email to: dev-unsubscribe@texera.apache.org

Re: [D] UX Feedback (Operator Descriptions) [texera]

Posted by "sshiv012 (via GitHub)" <gi...@apache.org>.

GitHub user sshiv012 added a comment to the discussion: UX Feedback (Operator Descriptions)

Text Input is a good candidate because its current description, “Source data from manually inputted text,” omits behavior that changes the output shape. The implementation produces one tuple containing the complete input for single string; otherwise, i believe it iterates over lines, applies offset/limit, and parses each line as the selected attribute type. A more useful description could be:
“Creates tuples from manually entered text. Single String emits the entire input as one tuple; other attribute types emit one parsed tuple per line. Offset and limit select which lines are emitted.” Or more generally, operator descriptions could follow a small template: input unit, output unit, important mode-dependent behavior, and failure conditions. I am thinking if we can build a backwards compatible template, kinda representing the above like optional structured field here,

```scala
case class OperatorDocumentation(
    summary: String,
    inputUnit: Option[String] = None,
    outputUnit: Option[String] = None,
    behavior: List[String] = List.empty,
    failureConditions: List[String] = List.empty
)
```

Based on my inspection, OperatorInfo currently exposes one free-form operatorDescription string, which the frontend renders directly. The UI could render the summary in the existing tooltip and show the remaining fields in an expandable details section. Keeping the field optional would allow operators to migrate incrementally while preserving existing descriptions.

GitHub link: https://github.com/apache/texera/discussions/6798#discussioncomment-17743378

----
This is an automatically sent email for dev@texera.apache.org.
To unsubscribe, please send an email to: dev-unsubscribe@texera.apache.org

Re: [D] UX Feedback (Operator Descriptions) [texera]

Posted by "xuang7 (via GitHub)" <gi...@apache.org>.

GitHub user xuang7 added a comment to the discussion: UX Feedback (Operator Descriptions)

Thanks for the discussion on operator accessibility. We also have a separate effort to generate a short sample video for each operator. Please see discussion #6871 for more details.

GitHub link: https://github.com/apache/texera/discussions/6798#discussioncomment-17773108

----
This is an automatically sent email for dev@texera.apache.org.
To unsubscribe, please send an email to: dev-unsubscribe@texera.apache.org

Re: [D] UX Feedback (Operator Descriptions) [texera]

Posted by "sshiv012 (via GitHub)" <gi...@apache.org>.

GitHub user sshiv012 edited a comment on the discussion: UX Feedback (Operator Descriptions)

Text Input is a good candidate because its current description, “Source data from manually inputted text,” omits behavior that changes the output shape. The implementation produces one tuple containing the complete input for single string; otherwise, i believe it iterates over lines, applies offset/limit, and parses each line as the selected attribute type. A more useful description could be:
“Creates tuples from manually entered text. Single String emits the entire input as one tuple; other attribute types emit one parsed tuple per line. Offset and limit select which lines are emitted.” Or more generally, operator descriptions could follow a small template: input unit, output unit, important mode-dependent behavior, and failure conditions. I am thinking if we can build a backwards compatible template, kinda representing the above like optional structured field here,

```scala
case class OperatorDocumentation(
summary: String,
inputUnit: Option[String] = None,
outputUnit: Option[String] = None,
behavior: List[String] = List.empty,
failureConditions: List[String] = List.empty
)
```

Based on my inspection, OperatorInfo currently exposes one free-form operatorDescription string, which the frontend renders directly. The UI could render the summary in the existing tooltip and show the remaining fields in an expandable details section. Keeping the field optional would allow operators to migrate incrementally while preserving existing descriptions. Operators could adopt it incrementally without rewriting every description at once. Would a structured, optional template fit the intended scope of this proposal?

GitHub link: https://github.com/apache/texera/discussions/6798#discussioncomment-17743378

----
This is an automatically sent email for dev@texera.apache.org.
To unsubscribe, please send an email to: dev-unsubscribe@texera.apache.org

Re: [D] UX Feedback (Operator Descriptions) [texera]

Posted by "chenlica (via GitHub)" <gi...@apache.org>.

GitHub user chenlica added a comment to the discussion: UX Feedback (Operator Descriptions)

Thanks for the comments.  @xuang7 please add the link to the discussion about generating a video to show how to use each operator.  If the discussion is not created, please create it.

GitHub link: https://github.com/apache/texera/discussions/6798#discussioncomment-17744667

----
This is an automatically sent email for dev@texera.apache.org.
To unsubscribe, please send an email to: dev-unsubscribe@texera.apache.org

Re: [D] UX Feedback (Operator Descriptions) [texera]

Posted by "Yicong-Huang (via GitHub)" <gi...@apache.org>.

GitHub user Yicong-Huang added a comment to the discussion: UX Feedback (Operator Descriptions)

I think this is a really important issue. We should make the documentation show up as closely as possible on the UI. I support reviewing the existing operators and improving their inline documentation. At the same time, the documentation/description should remain concise so users aren’t overwhelmed by unnecessary detail. Humen are lazy and they all want TL;DR. 

A related principle is: “If a variable needs extensive documentation, it may be better to rename it.” Improving how self-explanatory the interface is should also be one of our goals. If an operator property is difficult to explain clearly and concisely, we should consider revising its name or redesigning the property itself rather than relying solely on extensive documentation.

GitHub link: https://github.com/apache/texera/discussions/6798#discussioncomment-17774055

----
This is an automatically sent email for dev@texera.apache.org.
To unsubscribe, please send an email to: dev-unsubscribe@texera.apache.org