Expand / clarify documentation and UI references to variables

Marlan

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.

dimitri

Hi @Marlan
, thanks for this feedback! We have plans to improve our documentation about variables, and we'll make sure your ideas are taken into account.

We'll keep you updated on the coming changes.

Marlan

Sounds good, thanks @dimitri
!

Marlan

CoreyS

Hey @Marlan
, @AshleyW
and I are reviewing this idea and we were curious if you could clarify this idea along with another:

To us they sound rather similar so we just wanted to ensure we understand your proposed ideas and the differences between the two. Thanks in advance!

Marlan

Hi @CoreyS
and @AshleyW
,

OK, I just reviewed the Tim's Visual Guidance idea and my idea again and I would describe them as complementary.

I had two suggestions. The second one was more general and basically was to standardize the terminology for the various types of variables across the UI and documentation.

The first one was more specific to the Define Variable step in Scenarios. Here I was suggesting that the UI and documentation be more clearer about how to specify variables using a JSON block and to note the most common use case (at least for us) which is to override existing project variables for that scenario run.

None of my suggestions would require any change in functionality. All would be updates to text in the UI and in the documentation.

Tim's idea was to make the list of available variables (and where relevant the valid values of the variables) viewable within the UI. This would be an enhancement to the UI functionality. (It's a great idea by the way and definitely make for a more usable and friendly experience.)

I'd be happy to jump on a 5 minute Zoom call and show you exactly what I'm suggesting.

Thanks for circling back to clarify!

Marlan