Open dvdvgt opened 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:
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:
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.
Very good point @jiribenes . I would conflate the latter two groups though and potentially offer a few optional explanations.
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
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.