Contribution Guideline

A collaborative work on these lecture notes is an experiment, and therefore at the moment it is not clear how exactly the workflow should look like. Please treat information on this wiki page as a guideline rather than strict rules.

How to Contribute?

We work together on the .tex document using more or less the same methodology as in most community driven open-source projects. Just fork the repository, make local changes, and then send a pull-request. You can also contribute to this wiki, or share your ideas in discussions.

Working on a Chapter

For each chapter we have a separate .tex file. This file together with an initial structure of sections is created by the lecturer, usually the next day after the corresponding lecture. After that, there are three phases of working on a chapter/section:

1. adding the technical material,
2. writing some prose that elaborates on the ideas and technicalities,
3. an infinite loop of corrections.

Adding Technical Material

During this phase we add math definitions and formulations of the theorems into the .tex document with an optional laconic description. If you want to contribute in this way, just send a pull-request that expands the .tex document. Some hints about this phase are as follows.

• All relevant changes in this phase are merged into master very quickly: on this phase it is important to progress rapidly.
• Do not worry if your math typesetting looks ugly! Just push anything you have. We will fix math typesetting later, as it is easier to do it if it's already typed.
• If you need to define a LaTeX macro, define it at the beginning of the Section/Chapter. If some macro will be needed across several sections, we'll move it into the separate LaTeX package macros.sty. Since the "classic" LaTeX \newcommand and \renewcommand require, respectively, that the command is not already defined, or that it necessarily is defined, changes in one section may break definitions in another in case of a name collision. For this reason, this might be one of the rare cases where unconditionally overwriting macros is preferable, e.g., using TeX's \def or LaTeX3's \DeclareDocumentCommand. The syntax for the latter is something like this:

  \DeclareDocumentCommand\CmdNameGoesHere{mm}{Command body, with two mandatory args: #1, #2}

  However, try to be careful not to overwrite any macros from macros.sty or some other package!
• If you need to use some LaTeX package, that is not requires by the document yet, first check if the same functionality can be achieved using the packages already included (we try to avoid requiring too many packages). If not, you can freely add a \require directive at the beginning of the main .tex document.

Writing the Prose

As our ultimate goal is to create a math textbook with a beautiful narration and well explained ideas, each section should be filled in with an elaborate description of the presented technical material. At this stage try to obey the following rules.

• Describe each piece of technical material added in the previous phase.
• Try to focus on the main ideas and intuitions. Boring descriptions of math are boring.
• You can take inspiration from the lecture on how the narration could be carried on. But remember, writing a book is different than giving a lecture, so do not try to stick to the lecture at all costs.
• At this phase, we also want to progress rapidly. If you have something, just send a pull-request.
• If you have some half-baked description that you don't want to push into the repository, you can place it on a wiki page related to the corresponding chapter.

Infinite Loop of Corrections

When everything in a chapter is already typed, it does not mean that the chapter is done. There are always typos, grammar errors, the narration flow is not perfect, some descriptions are not clear, redundant or just too boring. The guideline for this phase is the following.

• Minor changes, like typos or grammar corrections are merged quickly. If you find such a minor error, just correct it and sent a pull-request.
• Major changes that change the narration flow should go through a peer review process. If you made such a change, also send a pull-request, but it will be merged or not after some discussion.
• If you have some controversial ideas on how to make a section better, start a new discussion.
• If you see that something should be done better, but you don't have clear ideas how to do it, write your comment on wiki or start a new discussion.

Collecting Bibliography

Each chapter has a Further Reading section. This section is intended to collect some additional pointers to the literature, that describe the topic of the chapter, or something related. If you know some interesting paper that should be placed there, just add (via pull-request) a citation at the end of this section and try to describe the citation in one sentence. The bibliography is managed via BibTeX and the references.bib file contains a local database of referenced work. You can add items to this file, but try to obey the following rules.

• The file is sorted in an alphabetical order.
• Each entry has a name that consists of the names of the authors and the last two digits of the publication year. If a paper has only one author use his last name, e.g., Huet97. If there are two authors, use both names preserving the order, e.g., PlotkinPretnar15. If there are three or more authors, use the last name of the first author and the first letters of the names of the remaining authors, e.g., PirogPS19. Do not use non-ASCII characters (PirogPS19 instead of PirógPS19). If you cite unpublished materials with an unclear "publication date", just omit the year, e.g., McBride. Finally, if these rules require two entries to have the same name, add a lowercase letter (a, b, ...) at the end of one of them.
• It is useful to use online databases (e.g., DBLP) for obtaining the correct bibliographical metadata.