Tutorial alpha user feedback: General

[sbrincat]

Here is feedback from my n=1 (me) alpha user testing of the tutorials. General feedback is in this issue, I'll put feedback specific to each individual tutorial in separate issues.

All the tutorials work for me now, and they are all really nice! The main overarching suggestion is that right now they each do a great job of replicating some model from a paper in tutorial form. But I think we need to next move toward being more didactic—being more explicit about what the user should learn from each tutorial, offering more explanation of NB functionality in each tutorial so users are gaining understanding, and guiding the user through the tutorials as a whole sequence.

Specific suggestions

• I think tutorials should try to be more explicit about what new NB concepts/functionality they are introducing. This should be mentioned within an introductory paragraph and/or bullet list in the header, and also highlighted at points within the tutorial when new concepts are introduced or added.
• I like how a few tutorials (e.g. “Bottom-up construction”, DCM) start with a bullet-point outline of what they will cover. I think this helps to orient users to what they will do/learn, and decreases likelihood of just cut-and-pasting through the tutorial without gaining understanding. I suggest all tutorials do this.
• When key new NB concepts/functions are introduced for the first time across the tutorials, it would be good to mention that in the associated tutorial text and link to the function in the “API” (or wherever in the documentation they live), so users can do a deeper dive into the function’s syntax/functionality if they want
• Relatedly, we should have full documentation for all Neuroblox functions publicly available somewhere before we fully roll out the tutorials/workshops. I would find it extremely frustrating if there were a bunch of calls to 3rd party functions with little to no explanation and no way to find what exactly they are doing and how to use them.
• Can we aim to minimize gratuitous use of new code constructs/syntax in tutorials? Ideally, the only new or different things that appear in a given tutorial should be the things you want the user to learn from the tutorial. When irrelevant new or modified things are included in a tutorial—especially without explanation—it can leave users confused and frustrated about what is important and what is the proper way to do things.
• I like the tutorials (e.g. “Bottom-up construction”) that included points where users are encouraged to tweak parameter values. This again encourages user interaction and likely promotes understanding. We should try to do that more where applicable.
• Several tutorials (Rest state, BG, DCM) generated plots that looked different from the website version, due to stochasticity. I think this could be confusing to users. Could we set a random seed at the start of each tutorial (as some do) to ensure repeatable results?

Minor suggestions

• I like the links to Julia resources added to Getting Started. I think it would be helpful to also offer brief explanations (e.g. in-line comment) within tutorials when a concept unique to Julia is first used (e.g. !, @nAmed, @parameters, @variables)
• Maybe this is due to my ignorance, but I’m not a huge fan of using a different solver method for each tutorial with no explanation of what the difference is or why one was chosen over another. As a user, you get the feeling that this is important, but you don’t know why, and you have no idea which to use if you want to build your own model. Maybe we can have a brief description when each is used, and/or maybe include a page somewhere listing different methods and their uses?
• Some tutorials use a semicolon to separate position and keyword arguments in function calls (e.g. add_edge!(g, WC1 => WC1; weight = -1)) and others just use all commas (e.g. add_edge!(g, WC1 => WC1, weight = -1), which are apparently totally equivalent(?). Could we maybe align on a single style? I think especially for people trying to learn Julia, having a lot of irrelevant differences can be confusing.
• When key new neuroscience or computational concepts are introduced, it might be nice to include a link to a wiki page (or something similar) for user who want a deeper understanding.
• Throughout the tutorials, the code contains many non-ASCII characters (Greek letters, symbols, subscripts, etc.). I have never seen this before! Maybe we could include a quick link somewhere (with the Julia links in Getting Started) that explains how to generate those?