UX Feedback (Operator Descriptions)

[Neilk1021]

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.

[sshiv012]

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,

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?

[chenlica]

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.

[xuang7]

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.

[Yicong-Huang]

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.