Documentation Issues and Suggestions

Hi Adam,

I went through bmlTUX documentation website and I made some notes, below, on what isn't very clear and some suggestions on improvement.

Getting Started Section

In the Getting Started page, the hyperlinks (i.e., cite, publication, Requirements, etc.) could stand out more, for instance add a bold format to them as they are hard to see they are links (at least for me).

Tutorials Section

Part 2: Creating a new Experiment

Install bmITUX

I suggest either having a link to the installation page or explaining that there are two installation procedure options, or else it seems like the old version of the installation is the recommended one (as it is the one explained in this section).

Set up the Unity Scene

Item 3: Name your Experiment "Tutorial", if you name it "Tutorial" the generated runner script file will be named as "TutorialRunner", not "TutorialExperimentRunner", this can be a bit confusing. I would update either the experiment name you use in your example to be "TutorialExperiment", and the associated image you provide, or the name of the Runner script files you address throughout your tutorial.

Part 3: Designing an Experiment

Test out our experiment design using basic components

Display Selection

It isn't clear how to choose which display will be used for the experiment (virtual environment) and which display will be used for the graphical user interface (new experiment session / preview table). By default they are both on display 1, so this part of the tutorial is a bit confusing on how to visualize both (in 2 different displays) at the same time.

You could mention here that the virtual environment display can be selected by choosing the MainCamera game object in the hierarchy window and then, in the inspector, using the Camera -> Target Display option to choose the desired display to use (i.e. Display 1).

You could then mention that to the graphical user interface display can be selected by selecting the TutorialSettings file in the Project window (located in the [Experiment_NameExperiment] folder) and in the inspector window under Gui Settings -> Target Display, selecting the desired display to use (i.e., Display 2).

Item 6

"In the default scripts, a trial is simply defined as pressing the return key. Press it a few times to see how the trials advance, and the values of the independent variables change."

At this moment in the tutorial there is no script that will go through the trials by pressing the return key (the default is set to the space key), so this is a bit confusing and seems like something is missing/not working correctly if you simply try to run and press the return key.

I suggest either mentioning that the user needs to press the space key (and then update Parts 4 & 5 of the tutorial to also show the space key in the code), or that this functionality will appear in the next step of the tutorial (Part 4: Writing Runner Scripts), or adding part 4 here and moving Item 6 to appear after Part 4.

Part 4: Writing Runner Scripts

Setting up the Stimuli

I would change the phrase: "Let’s first position our main Camera to 0,0,0, and have it pointing along the Z axis." to "Let’s first position our main Camera at 0,0,-10, and have it pointing along the Z axis (rotation as 0,0,0)." If you do not mode the Camera Z position back the capsules will not show up on the camera, as they are in the same Z position of 0.

Outputting Data

Your code example is missing a ";" at the end

protected override void PostMethod() {
    Data["MatchedSize"] = tutorialRunner.MatchObject.transform.localScale.x; <----- here
}

Part 5: Defining Blocks

Block Variables

"Recall that we set up the distance variable as a block variable." this wasn't done in the tutorial, or at least it wasn't clear where in the tutorial this was set up. Maybe remove/change this phrase?

Update Block Script

"1. Open TutorialBlockScript.cs." should be "1. Open TutorialBlock.cs." (there is no word "Script" at the end of this script file name). This should also be updated in the code you provide (i.e., "public TutorialBlockScript" should be "public TutorialBlock").

Randomization

"In the top of the config file inspector, select the following settings:", it is not clear what the config file is here. It might be clearer to say something like "With the TutorialDesign file selected, in the top of the inspector, select the following settings:"

Documentation Section

Creating an Experiment

Configuring your experimental design

The "VariableConfigurationFile Screenshot" is missing here.

Accessing GameObjects and Scripts in your Scene

I suggest changing the ExperimentRunner gameObject access example "GameObject gameObjectInScene = myRunner.SomeReferencedGameObject;" to "GameObject gameObjectInScene = myRunner.gameObjectThatMoves;" as it will be easier to understand that this "gameObjectThatMoves" object being accessed in the Trial script ((or another script) is the same object that was created/referenced in the Runner script you used as an example.

Advanced Options

Customized Settings - Where can I find the "FileLocationSettings" option? I do not see it in the Settings file, was it removed in the current version (2.0.2)?

General Notes

In multiple places of your documentation you use either "BML_TUX", "BML", or "bmlTUX" when referencing this asset's menu name in the Unity menu bar. It would be good to standardize this to "bmlTUX" menu, as this is the one used in the current version (2.0.2). I didn't keep track of all the places they were used, but I believe I saw more "BML_TUX" and "BML" in the documentation sections.

I know this is a lot of information but I hope it helps.

BioMotionLab / TUX

Documentation Issues and Suggestions #43