Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add extensive language tutorial #37

Open
dvdvgt opened this issue Nov 2, 2023 · 2 comments
Open

Add extensive language tutorial #37

dvdvgt opened this issue Nov 2, 2023 · 2 comments

Comments

@dvdvgt
Copy link
Contributor

dvdvgt commented Nov 2, 2023

Currently, the documentation on the website is quite sparse given the complexity of the language. I would like to discuss the addition of an extensive, in-depth language tutorial. This is not to be written for inexperienced programmers, but rather assumes previous programming (languages) knowledge (akin to the "Rust Book") by being example driven in its explanations. I can imagine the following outline

  1. Basics
    1. Expressions & Statements
    2. Variables (mutability)
    3. Functions & Types
    4. Value & block parameters
  2. Algebraic Effects
    1. Motivation
    2. Effect definition
    3. Effect handling
    4. Example
  3. Advanced Features
    1. Boxing
    2. Bidirectional Effects
    3. Objects
    4. ...
  4. Project
    • Here, most of the things introduced in the language tutorial should be revised by constructing a little project that the reader can follow along with.

Please note that I have not been able to keep up with all the advanced features that have been added. Thus, this outline is very much open for discussion and I will happily integrate your suggestions and feedback.

@jiribenes
Copy link
Contributor

It would be nice to distinguish different kinds of readers ("personas"). Off the top of my head, I can namely think of three groups:

  1. experienced programmers who want to play around with the language
  2. language implementors/researchers who don't know about effect systems
  3. language implementors/researchers who do know about (other) effect systems

All of those groups probably want to see a version which is slightly different.
I've seen a similar problem solved by Tomáš Petříček in his interactive introduction to his PhD thesis and in Technical Dimensions of Programming Systems:
Here's a screenshot of the former which allows the reader to pick one of the four possible versions:
Screenshot 2023-11-02 at 11 27 50

We wouldn't possibly have to go this interactive, but I believe it's important to think about which tutorial pages are meant for which audience.

@b-studios
Copy link
Collaborator

b-studios commented Nov 2, 2023

Very good point @jiribenes . I would conflate the latter two groups though and potentially offer a few optional explanations.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants