[hotfix] [docs] Rework 'Name and Description' section of operators overview to improve grammar and clarity #27201
Conversation
| The name of operator and job vertex will be used in web ui, thread name, logging, metrics, etc. | ||
| The name of a job vertex is constructed based on the name of operators in it. | ||
| Operator and job vertex names are used in the web UI, thread name, logging, metrics, etc. | ||
| The name of a job vertex is constructed using the names of operators it contains. |
There was a problem hiding this comment.
nit: "operators" -> "the operators"
| The description of a job vertex is constructed based on the description of operators in it. | ||
| The description can contain detail information about operators to facilitate debugging at runtime. | ||
| The description of a job vertex is constructed using the descriptions of the operators it contains. | ||
| The description can contain detailed information about operators to facilitate debugging at runtime. |
There was a problem hiding this comment.
when we say "is constructed" do we mean that Flink code constructs it, or user code? If it is Flink code then we should give an example of how the descriptions are constructed. If is is user code then we should make it obvious from the wording that this is advice / good practise around description content.
The line above "The name needs to be as concise as possible to avoid high pressure on external systems." I would suggest changing this to something like , the name should be descriptive, unique (within what ever scope); and concise (why does a long name create high pressure on external systems?)
|
|
||
| Operators generated by Flink SQL will have a name consisted by type of operator and id, and a detailed description, by default. | ||
| Users can set `table.exec.simplify-operator-name-enabled` to `false`, if they want to set name to be the detailed description as in former versions. | ||
| By default, the description of a job vertex is organized in a multi-tree line mode. |
There was a problem hiding this comment.
what does multi-tree line mode mean?
| Operators generated by Flink SQL will have a name consisted by type of operator and id, and a detailed description, by default. | ||
| Users can set `table.exec.simplify-operator-name-enabled` to `false`, if they want to set name to be the detailed description as in former versions. | ||
| By default, the description of a job vertex is organized in a multi-tree line mode. | ||
| To use a single line cascading mode, set `pipeline.vertex-description-mode` to `CASCADING` |
There was a problem hiding this comment.
I suggest giving examples of these modes
|
|
||
| When the topology of the pipeline is complex, users can add a topological index in the name of vertex by set `pipeline.vertex-name-include-index-prefix` to `true`, | ||
| so that we can easily find the vertex in the graph according to logs or metrics tags. | ||
| By default, operators generated by Flink SQL will have a name composed of the operator type and id. Details will remain in the description. |
There was a problem hiding this comment.
you mention "Details will remain in the description.". What details are these - it would be better to list them.
You say remain - I am not sure what we are trying to say with this. I suggest something like:
"The description contains more information on the operator including ...."
| When the topology of the pipeline is complex, users can add a topological index in the name of vertex by set `pipeline.vertex-name-include-index-prefix` to `true`, | ||
| so that we can easily find the vertex in the graph according to logs or metrics tags. | ||
| By default, operators generated by Flink SQL will have a name composed of the operator type and id. Details will remain in the description. | ||
| To include the description, set `table.exec.simplify-operator-name-enabled` to `false` |
There was a problem hiding this comment.
I would think table.exec.simplify-operator-name-enabled
true : would mean a simplified name with more details in the description.
false: would mean a more complicated name including elements of the description. Does this mean there is no description?
I am not sure this sentence is saying that. Did I understand correctly?
github-actions
bot
added
the
community-reviewed
3 participants
What is the purpose of the change
Reworks the 'Name and Description' section of
content/docs/dev/datastream/operators/overview.mdto improve grammar and clarity.