We follow a simple workflow for the creation of tutorials.
To summarize it, roughly, in one line:
- readiness announcement -> selection of reviewer -> review process -> acceptance/disapproval -> announcement -> webpage
Here it is, in detail:
- Start - an announcement at the #scicloj-tutorials Zulip stream, under a separate thread ("topic"), that the tutorial/article is ready for review.
- (optional) The author may ask specific people from the group by name for review.
- Someone takes responsibility as the reviewer, and creates a private Zulip stream for discussion.
- The reviewer checks for the following basic requirements:
- instructions how to run the provided code, to achieve the same or similar results;
- obligatory sections: intorduction/abstract about the topic coverage list (goals), instalation/running notes, conclusion/summary;
- a link to the relevant Zulip discussion, as well as a note how to contact the author (mail, Zulip, github, etc.).
- The reviewer proceeds with the following:
- kind of a scientific review, if the topic covers some theoretical parts;
- walking through the whole tutorial/article, trying to run all the code.
- Feedback is given in a private stream (important: always explain why and be polite):
- all the stuff found during checks;
- gaps in narration;
- (optional) possible enhancement.
- The author incorporates the reviewer's suggestions (or not, if they are not applicable).
- This process iterates, until both decide to stop (with or without success).
- The reviewer comments, under the above #scicloj-tutorials topic dedicated to the tutorial, about the conclusions (approval or not, if not - why, maybe other review is needed).
- The author decides where and when to announce the article.
- In a case where the reviewer accepts the tutorial/article, a link to will be added at the scicloj website.