Improving the tutorial

[alkrasnokutskaya]

It makes sense to me as a user to:

• move the installation & environment part in the beginning
• put basic syntax as the 2nd part
  Without those, the "quick tour" is hard to understand, impossible to follow and you have to come back to it anyway

[otherjoel]

Thanks for the feedback, which makes sense for the documentation in its current state. Let me share the reasoning behind the ”quick tour” tutorial’s content and placement — which might help — and then, any further feedback will also be very welcome.

The current outline includes a "Conscript" section (section 3) that begins with installation (3.1) followed by a section for detailed tutorials (3.2) that properly “begin at the beginning”, including basic syntax. Of course, 3.2 is being written and isn’t done yet. But my initial thought in response here is that when it is finished, section 3 will, in itself, be the documentation with the ordering that you expect.

A couple of core assumptions/requirements are shaping the docs’ structure:

1. The Congame docs must address both the Conscript study authoring environment and the Congame server-side application.
2. The typical Conscript user/reader should be shielded from the complexities of the server-side stuff.

The tension between these has resulted in the outline you see now; it’s why the "Conscript" section is No. 3 and not No. 1 in the outline. It’s why the tutorial in section 1 isn't super detailed. It really is meant only as a tour, to quickly show people in a general sense what Conscript and Congame study development workflows look like in practice from beginning to end, in one fell swoop. The tutorials that will be placed in sections 3 and 4 will serve as the real educational blocks that build step-by-step: installation to syntax to simple functionality to advanced.

As I said, feedback is welcome. Perhaps the two assumptions/requirements above might need revisiting. Or perhaps the quick tour is missing some explanations that would help.

[MarcKaufmann]

Two comments:

1. @alkrasnokutskaya probably meant the installation of conscript/local should come first -- or the docker instructions once we have removed conscript/local -- not how to set up the full server. I agree that the full installation should be postponed. I would include the high-level installation (1. clone this repo 2. install docker 3. run docker compose up in the repo) in the Quick tour with a link to a more beginner-friendly step-by-step instruction that is in a separate part of the docs, providing detailed steps on what cloning a repository means (or how to download it as a zip via the web interface).
2. The syntax makes more sense after the Quick tour, but we should highlight at the start that the Quick tour is not meant to get a user to write studies by itself. Rather it is to get a taste of conscript, and learn the workflow of writing, updating, and running studies. Once we have more documentation, we may want to provide more guidance on which part is for which type of user - in the spirit of https://docs.racket-lang.org/getting-started/index.html.

[MarcKaufmann]

I'll close this for now as the tutorial has changed a bit.

[MarcKaufmann]

Reopening to use as the general place for comments on tutorial.

[alkrasnokutskaya]

@otherjoel Hi! Not sure, if this part of the tutorial is in the future, just leaving the comment to remember

I wanted to look up "How to select a random value from a list of items" in the tutorial and expected a one-liner because really I just needed the name of the function that picks a random value. But in the tutorial you get several pages of code and have to look through it to get that one short line of code you need.
Of course, having an example of the implementation is great but for such simple tasks I think it makes sense to provide one-liners in the beginning :)

[MarcKaufmann]

I don't see this in the tutorial, maybe you mean this: https://docs.totalinsightmanagement.com/Conscript__Original_.html#%28part._.How_to_select_a_random_value_from_a_list_of_items%29. That is an old cookbook, but it is wrong code anyway, since it uses get and put.

Once we change this, it should be shorter and only include the part where the choice-that-counts is selected - here the step called display-payment, or some better version of that. @otherjoel: remove unnecessary setup - although testing of cookbooks should be done (eventually via bots), so we should have full examples in congame-example-studies/ that we can link to (or in some other folder).

But it sounds like what you wanted was (random-ref '(a b c)). That is a Racket question, more than a conscript question, and we should not try to document standard Racket. For questions that are about Racket (ask yourself whether this is about general programming or about study-specific things such as setting or getting values, repeating studies, etc), google/ChatGPT it as a general Racket question first.

Later we may add a 'Quick Tour of Racket Concepts for Conscript' to cover common Racket issues that are in too many different places in the Racket docs.