admin2/manual_teachbooks
1
0
Fork 0
mirror of https://github.com/TeachBooks/manual.git synced 2026-11-12 22:35:51 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Organize team stuff

Browse source
This commit is contained in:
Tom van Woudenberg 2024-05-27 15:56:27 +02:00
parent c8483ccc9a
commit 26111d87c8
3 changed files with 6 additions and 5 deletions
Download patch file Download diff file Expand all files Collapse all files

2
book/_toc.yml
View file

@ -21,7 +21,7 @@ parts:
- file: workflows/edit_book
- file: workflows/check_changes_online
- file: workflows/merge_request
- file: installation-and-setup/organize_team
- file: installation-and-setup/organize-team
- caption: Features
chapters:
- file: basic-features/overview

7
book/installation-and-setup/organize_team → book/installation-and-setup/organize-team.md
View file

@ -2,7 +2,7 @@
```{admonition} User types
:class: tip
This page is useful for user type 3-5.
This page is useful for user type 4-5.
```
If you want to create a collaborative book for students, there's a few agreements you should make to enhance collaboration and student experience. These are written from our own experience, feel free to deviate or provide your own advice!
@ -11,8 +11,8 @@ If you want to create a collaborative book for students, there's a few agreement
## Team
- Define who's in charge of:
- Team organization (administrators)
- Combining content (maintainers)
- Team organization (administrators), at least user type 4
- Combining content (maintainers), at least user type 4
- Editing and reviewing content (editors)
- Define how your review process is taking place. We advice at least a maintainer reviewing each bit o content.
- Make sure people identify themselves as one of the user types. You should have at least one user type 4 or 5. Although this can be a TA, it is advised one of the teachers is comfortable with this user type as well.
@ -29,6 +29,7 @@ If you want to create a collaborative book for students, there's a few agreement
- Add people with GitHub/GitLab permission matching their role and the protected branches.
- Add a readme explaining the way you organized branches and permissions
- Provide explanation on how you'd like to receive feedback in both the readme as the published book. The use of issues (in the book with the issue button) is advised.
- Decide on whether or not to publish your book via Open Interactive Textbooks TU Delft. Publishing will give you a copyright check, ISBN and DOI number but heavily limits the amount of changes you can make to your book. We advise publishing an archived version of your book whenever the academic year is over.
### GitHub vs GitLab

2
book/installation-and-setup/user_types.md
View file

@ -2,7 +2,7 @@
Different types of users will interact with the website or the Jupyter Books differently and will therefore need to know more or less about the composition of the book. For now we will differentiate 6 types of users.
1. **Students providing feedback on the published website**.<br> <img src="figures/type 1.jpg" alt="Example Image" align="right" width="130" style="margin: 10px;"> There are multiple tools of providing feedback in the built book: a) Using the [hypothesis](https://jupyterbook.org/en/stable/interactive/comments/hypothesis.html)-extension which allows public/private highlighting and annotating parts of the book. An example can be seen on the [MUDE website](https://mude.citg.tudelft.nl/book/intro.html). b) Using the [Utterances](https://jupyterbook.org/en/stable/interactive/comments/utterances.html)-extension which allows commenting on pages for books which are hosted on GitHub. Those comments are converted to issues on GitHub for the editors to handle.
1. **Students providing feedback on the published website**.<br> <img src="figures/type 1.jpg" alt="Example Image" align="right" width="130" style="margin: 10px;"> There are multiple tools of providing feedback in the built book: a) using the issue button in the top-right corner to directly create issues visible to the editor team. b) Using the [hypothesis](https://jupyterbook.org/en/stable/interactive/comments/hypothesis.html)-extension which allows public/private highlighting and annotating parts of the book. An example can be seen on the [MUDE website](https://mude.citg.tudelft.nl/book/intro.html). c) Using the [Utterances](https://jupyterbook.org/en/stable/interactive/comments/utterances.html)-extension which allows commenting on pages for books which are hosted on GitHub visible for everyone. Those comments are converted to issues on GitHub for the editors to handle.
2. **Colleague providing feedback on the draft website**. <br>
In a similar manner as students, colleages and team members can leave content related comments on the website through extensions. In this way, multiple teachers can give input in the draft of the textbook and course material without requiring and exact understanding of Jupyter Books or GitLab/GitHub. The responsible teacher (or student assistants) can then make the adaptations to the book as recommended by their colleagues.