diff --git a/book/installation-and-setup/figures/type 1.jpg b/book/installation-and-setup/figures/type 1.jpg deleted file mode 100644 index 6abc607..0000000 Binary files a/book/installation-and-setup/figures/type 1.jpg and /dev/null differ diff --git a/book/installation-and-setup/figures/type 5.jpg b/book/installation-and-setup/figures/type 5.jpg deleted file mode 100644 index f9e96dd..0000000 Binary files a/book/installation-and-setup/figures/type 5.jpg and /dev/null differ diff --git a/book/installation-and-setup/figures/usertype1.jpg b/book/installation-and-setup/figures/usertype1.jpg new file mode 100644 index 0000000..f02af71 Binary files /dev/null and b/book/installation-and-setup/figures/usertype1.jpg differ diff --git a/book/installation-and-setup/figures/usertype2.jpg b/book/installation-and-setup/figures/usertype2.jpg new file mode 100644 index 0000000..9979094 Binary files /dev/null and b/book/installation-and-setup/figures/usertype2.jpg differ diff --git a/book/installation-and-setup/figures/usertype3.jpg b/book/installation-and-setup/figures/usertype3.jpg new file mode 100644 index 0000000..582e4fa Binary files /dev/null and b/book/installation-and-setup/figures/usertype3.jpg differ diff --git a/book/installation-and-setup/figures/usertype4.jpg b/book/installation-and-setup/figures/usertype4.jpg new file mode 100644 index 0000000..19979da Binary files /dev/null and b/book/installation-and-setup/figures/usertype4.jpg differ diff --git a/book/installation-and-setup/figures/usertype5.jpg b/book/installation-and-setup/figures/usertype5.jpg new file mode 100644 index 0000000..56c0786 Binary files /dev/null and b/book/installation-and-setup/figures/usertype5.jpg differ diff --git a/book/installation-and-setup/user_types.md b/book/installation-and-setup/user_types.md index 3dfadc8..8bd924c 100644 --- a/book/installation-and-setup/user_types.md +++ b/book/installation-and-setup/user_types.md @@ -2,22 +2,74 @@ 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 5 types of users. -1. **Students providing feedback via the book website**.
- Example Image
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. 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. +## User type 1: Students providing feedback via the book website -2. **Colleague providing feedback on a draft website**.
- In a similar manner as students, colleages and team members can leave content-related comments on the website through extensions or GitHub/GitLab features (e.g., Issues). In this way, multiple teachers can give input in the draft of the textbook and course material without requiring a complete understanding of Jupyter Books or GitLab/GitHub. The responsible teacher (or student assistants) can then make adaptations to the book as recommended by their colleagues. +```{figure} figures/usertype1.jpg +--- +name: usertype1 +width: 300px +align: center +--- -3. **Colleague making adjustments via the browser**.
- This type of user requires only very basic knowledge in GitLab/GitHub in order to make changes to the website themselves. Most iportantly, there is no need to install any software! Making adjustments to a file only requires the user to be able to login into GitLab/GitHub and edit .md or .ipynb files. The changes can be done directly in an existing branch, or, if unsure, a new branch can be used for the changes then the set-up and merging can be completed by someone more familiar with GitLab/GitHub. Files can be edited individually or many-at-a-time using the VS Code-style browser application. +``` -4. **Colleague making adjustments locally**.
- User 4 is a hybrid between type 3 and 5. Basically this user is making changes by editing the .md files locally using, for example, VS Code. Therefore, this user requires a little bit more knowledge on git (think of pulling and pushing changes) but their main focus remains to make adjustments to the content of the book by editing .md files whereas user type 5 has more knowledge to make changes to python files the book as well. This user can build the book online and therefore does not need to have special software installed besides a text editor (e.g., Python is not required). +There are multiple tools of providing feedback in the built book: -5. **Colleague making adjustments and incorporating them in the book locally**.
- Example Image
This user has more knowledge in GitLab/GitHub than the previous user and can take care of branching and merging directly. They know how to work with software for editing .md and .ipynb files. They can use the Deploy Book Workflow online to view their changes in the book and coordinate peer review, and/or build the book locally. +1. using the issue button in the top-right corner to directly create issues visible to the editor team. +2. Using the [hypothesis](https://jupyterbook.org/en/stable/interactive/comments/hypothesis.html)-extension which allows public/private highlighting and annotating parts of the book. +3. 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. -
+## User type 2: Colleague providing feedback on a draft website + +```{figure} figures/usertype2.jpg +--- +name: usertype1 +width: 300px +align: center +--- + +``` + +In a similar manner as students, colleages and team members can leave content-related comments on the website through extensions or GitHub/GitLab features (e.g., Issues). In this way, multiple teachers can give input in the draft of the textbook and course material without requiring a complete understanding of Jupyter Books or GitLab/GitHub. The responsible teacher (or student assistants) can then make adaptations to the book as recommended by their colleagues. + +## User type 3: Colleague making adjustments via the browser + +```{figure} figures/usertype1.jpg +--- +name: usertype3 +width: 300px +align: center +--- + +``` + +This type of user requires only very basic knowledge in GitLab/GitHub in order to make changes to the website themselves. Most importantly, there is no need to install any software! Making adjustments to a file only requires the user to be able to login into GitLab/GitHub and edit .md or .ipynb files. The changes can be done directly in an existing branch, or, if unsure, a new branch can be used for the changes then the set-up and merging can be completed by someone more familiar with GitLab/GitHub. Files can be edited individually or many-at-a-time using the VS Code-style browser application. + +## User type 4: Colleague making adjustments locally + +```{figure} figures/usertype4.jpg +--- +name: usertype1 +width: 300px +align: center +--- + +``` + +User 4 is a hybrid between type 3 and 5. Basically this user is making changes by editing the .md files locally using, for example, VS Code. Therefore, this user requires a little bit more knowledge on git (think of pulling and pushing changes) but their main focus remains to make adjustments to the content of the book by editing .md files whereas user type 5 has more knowledge to make changes to python files the book as well. This user can build the book online and therefore does not need to have special software installed besides a text editor (e.g., Python is not required). + +## User type 5: Colleague making adjustments and incorporating them in the book locally + +```{figure} figures/usertype5.jpg +--- +name: usertype1 +width: 300px +align: center +--- + +``` + +This user has more knowledge in GitLab/GitHub than the previous user and can take care of branching and merging directly. They know how to work with software for editing .md and .ipynb files. They can use the Deploy Book Workflow online to view their changes in the book and coordinate peer review, and/or build the book locally. ```{Note}