I have two suggestions on documentation improvement regarding variables.
First is that in a Define Variable step in a Scenario, one can use JSON to either define a new variable or (I believe more commonly) override / redefine a project variable. Two clarifications would be helpful.
One is to give an example of specifying a variable definition using JSON. The documentation says you can use a JSON object. Well, that isn't completely clear at least on a first read. I get it, it's a full specification like { "varname" : 1 } including the braces. But not everyone will immediately understand what a JSON object is. It would also help to clarify this in the UI. All it says there is "raw". Not very helpful.
Two is to clarify that one can override / redefine project variables in a Define Variable step (vs defining new variables). I confirmed that this is true in test a while back then forgot and had to confirm it again. It would be great to clarify this in the documentation (and in UI as well).
Second is that the language around project variables is inconsistent and confusing. The UI for defining project variables has Global variables section and Local variables section. I understand the distinction between global and local variables in this context (and it is a helpful feature) but not sure how well this is explained in the documentation or UI. Then scenarios have steps for updating project variables and global variables. Well the project variables in the step are the global/local variables in the Variables menu. And global variables in the step are instance variables. The variables 101 knowledgebase article that had misleading language at one point (but clearer language elsewhere).
The idea is thus to expand and clarify documentation and UI references to variables. For example, it would be great if project variables were referred to a project variables everywhere and instance variables referred to as instance variables everywhere in documentation and the UI.