Project Decisions¶
If you are curious why worksheet.cc does certain things the way it does and not differently, this section is for you. This should give you an idea about some of the design decisions that may appear arbitrary and surprising at first.
Curated set of exercises¶
In the era of Artificial Intelligence (AI), it appears that the crafted work is no longer considered important. However, the experience and creativity of the teacher are attributes that are difficult to replicate. Consequently, we believe in a curated set of exercises created by humans for humans.
This approach implies that the growth of this set will be slower than if we were to utilize AI.
Free format¶
Exercises should not be required to be written in a specific format. Users should be able to choose the language in which they write their exercises, such as LaTeX, ConTeXt, AsciiDoc, or any other format they prefer.
The format is crucial for only one reason: we are unable to combine exercises that utilize multiple formats because we cannot produce a cohesive worksheet. For instance, we cannot combine ConTeXt and LaTeX exercises because, ultimately, we must compile them in either LaTeX or ConTeXt.
To combine exercises, we could convert from one format to another using various tools, such as Pandoc. However, some formats are exclusively destination-only (see –format option). Therefore, users should consider this when writing their own exercises, as a more specific format may imply a certain level of incompatibility, making it difficult to combine with other exercises that utilize more general formats.
Although this may pose some challenges, we prioritize the freedom of users and believe that imposing a specific format would be counterproductive.
In this regard, we recommend utilizing syntax in YAML headers.
Writing exercises not worksheets¶
Prior to this project, I created a similar project. This project had a set of worksheets written in ConTeXt. Within these worksheets, there was embedded code in ERB, which basically established the corresponding parameters and displayed certain information depending on them. To obtain a specific worksheet, we simply executed ERB.
However, this approach had a problem: sometimes we wanted to extend worksheets, which meant rewriting them. And we also could not combine exercises from different worksheets to obtain, for example, a review worksheet for the entire course.
To avoid all these problems, after a period of reflection, it became clear that the most convenient approach was to write individual exercises rather than worksheets.
Separate exercises from templating sytems¶
In a general overview, we use a templating system to write the information from several exercises into a desired format to obtain a worksheet. In this sense, this allows us to separate the aspect from the contents.
We do believe external templating systems give more freedom than templating system embeded in exercises themselfs and, more importantly, it is easy to write by non-expert people. In an ideal scenario, the worksheet, and even less the exercises themselves, should not depend on the templating system.
This is the opposite of what AutomaTex does, which defines templates using LaTeX variables. This project is a great project created by Thomas Mounier, Maud Sindeff and Cyril Iaconelli and licensed under the Creative Commons CC-BY 4.0 license. Congratulations from here.
In practice, the templating system and the worksheet are interdependent, since the latter is written in a specific templating system (in our case, Jinja). The exercises themselves also depend on the templating system to some extent, as they contain variable declarations (in Python code or using Jinja’s set statements - see Tutorial), although the dependence is minimal. A completely independent system would be very complex to implement, as it would require writing a parser for a specific grammar (DSL - Domain-Specific Language).
