effekt-lang / effekt-website

Website of the effekt language
https://effekt-lang.github.io/effekt-website
MIT License
3 stars 4 forks source link

Add extensive language tutorial #37

Open dvdvgt opened 8 months ago

dvdvgt commented 8 months ago

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 commented 8 months ago

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 commented 8 months ago

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