Create a full cookbook of documentation

[shippy]

• [x] Go through all the issues closed since #23 and do the requisite README updates
• [ ] On the example of RA reversal learning, illustrate the steps needed to make a functional task
• [x] Document steps to extend R&A tasks
  • [x] Separate out the changes that a user might want to do in order to implement MDM from RA, and SODM from MDM

[shippy]

Things that came up with @rj299 & @sdk39 (thank you both!):

• [x] How do the config files work? What's the relationship between lib/config.m, tasks/XYZ/XYZ_config.m and tasks/XYZ/XYZ_config_A.m?
• [x] How does generating trials work? (With MDM, documenting well how generateTrials and generateBlocks works is especially important.)
• [x] How does the master script know which blocks to execute? How can I split a task into two sessions?
• [x] Where are the results saved? What structure are they saved in?

[shippy]

Quoting from #26:

This will definitely problematize the cookbook (#62). It's yet another approach to get things done. At this point, in decreasing level of removedness from code, we have:

1. Write your task with phase abstractions, re-using & configuring existing draw & action scripts. No need to write any trial or phase scripts -- just specify in drawCmds and action whatever you need.
2. Re-use phase scripts fully, but specify what callbacks they should have in XYZ_runTrial (and have phase scripts construct their ad-hoc phase configs before the callback).
3. Write those phase scripts that draw slightly different elements and/or take slightly different action than the general-library phase scripts. Re-use some draw scripts and/or action scripts, and re-use runTrial and runBlock. (see: current version of tasks/UVRA)
4. Write separate trial and phase scripts for each task (never did that)
5. Write separate block scripts for each block (see: initial_RA branch).

Documenting approaches (1)-(3) seems like a good next step.

[shippy]

Note: The right place for this is in docs/, not the wiki.

[shippy]

62_docs branch has a good start. A particularly useful entry point is this article.

[shippy]

How can I test that the documentation is sufficient?

Ask someone who is worked with the framework a little to implement a new task while mostly relying on the docs. Here are some ideas, and what problems would need to be overcome in order to implement them:

• a risk and ambiguity task with choice between 2 lotteries
  • This renders choseLottery meaningless, and requires the choice fields to be reliable. (Which it should, but see #115.)
  • drawLotto relies on offCenterByPx set in the configuration file. It does not assume that the same configuration file could want to call it with different off-center values. In other words, this might require implementing #98.
  • drawLotto & generateTrials assume that there is exactly one winning payoff, and possibly that there is a reference. This might require refactoring.
• A risk and ambiguity task with varying reference levels and different ambiguity mid-splits (i.e. not at 50%).
  • generateTrials assumes that all ambiguity combinations use the 50% value as a split — so, ambiguityCenter would need to be introduced to .generate and generateTrials would need to be fixed.
  • It’s possible that probability numbers would be displayed badly because a high or a low ambiguity center point wouldn’t leave them enough space. That said, that can be tested and such extreme points avoided.

Of course, all of this might take anyone a day or two, so the new task had better be worthwhile.

[shippy]

• [ ] Add code snippets where they are omitted
• [x] Tear Advanced features apart and reintegrate it into FAQ and other articles.

[shippy]

Complete:

• [ ] Article on conditions
• [ ] Update the outdated IDE in "Defining payoffs in R&A tasks"
• [ ] Add importing trials from CSV to "Generating trials"
• [ ] Add a main task script skeleton (pulled from a test case) to "Creating a task"
• [ ] Add a trial/block generation example to "Generating blocks"
• [ ] Add a counterbalancing example to "Generating blocks"
• [ ] Add a section about display / positioning default in "Defining payoffs in R&A tasks"
• [ ] Expand on the outline of "The life-changing magic of function handles"
• [ ] Add a specific example to "Exporting data"
• [ ] Extract configDefault documentation through Matlab Publish in "Configuring task"
• [ ] Build reversal learning paradigm for "Trial and its phases"

Missing: overview of the standard library, but that seems like the task for a different issue / something to do with Sphinx (#123).

I would say that at this point, despite the incompleteness, this might be good enough to have someone read through it and provide an independent voice.