From cfdd56d035db7dd918e15c55dc5df69c0b853809 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 28 Oct 2024 09:40:41 +0100 Subject: [PATCH] Update organize-team.md --- book/installation-and-setup/organize-team.md | 55 ++++++++++++++------ 1 file changed, 40 insertions(+), 15 deletions(-) diff --git a/book/installation-and-setup/organize-team.md b/book/installation-and-setup/organize-team.md index 18ccbc0..c7e8ea1 100644 --- a/book/installation-and-setup/organize-team.md +++ b/book/installation-and-setup/organize-team.md @@ -7,14 +7,12 @@ 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! -**This page is work in progress** - ## Team - Define who's in charge of: - 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. +- Define how your review process is taking place. We advice at least a maintainer reviewing each bit of 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. ## Tools @@ -35,23 +33,50 @@ If you want to create a collaborative book for students, there's a few agreement ### GitHub vs GitLab -- Github allows you to host your book on the GitHub server using GitHub pages (to be recognized by the `.github.io/` url, for example the [template book](https://teachbooks.github.io/template/)), which takes all the steps of hosting out of your hands. You can also use a custom owned URL, although this requires some additional skills. On TU Delft's GitLab you need a webserver, which is offered by TeachBooks (to be recognized by the url `teachbooks.tudelft.nl/`, for example [this manual](https://teachbooks.tudelft.nl/jupyter-book-manual)) as the TU Delft OIT team (to be recognized by the url `interactivetextbooks.tudelft.nl/`, for example [the TU Delft OIT demo book](https://interactivetextbooks.tudelft.nl/open-textbooks-demonstration/)). For the TU Delft OIT webserver you’re required to publish your book more officially, it cannot be used for viewing your book online in an active editing-phase. -- On GitHub you can start right away with a git environment and online book using our [template](../external/template/README.md). On GitLab you can set up your own git environment, but you need to be given access by [TeachBooks](mailto:teachbooks@tudelft.nl) or [TU Delft OIT](mailto:Interactive-textbooks@tudelft.nl) to view your build book online. -- On GitHub we developed a [automatic process which builds the book and publishes it online](../external/deploy-book-workflow/README.md) in a very flexible way (publication of multiple version of the book, insights in book building errors, parallel so fast build, custom urls in subdirectories). On GitLab both we and other people at TU Delft have a more simplistic workflow which can be used when you're set up on those Git environments and webservers. If you want to use GitLab but still want to make use of the GitHub workflow, you can [mirror your repository to GitHub](https://docs.gitlab.com/ee/user/project/repository/mirror/push.html#set-up-a-push-mirror-from-gitlab-to-github) -- When you’re publishing your book on a server on which you're in control (connected to GitLab or GitHub), you can set up SSO login for visitors of the website. This can be arranged for on the TeachBooks server. If you want the same functionality with GitHub pages, your book should be part of the [GitHub Enterprise of TU Delft](https://github.com/enterprises/tudelft). This SSO login is a bit different as you're required to give access to specific accounts. Furthermore, the url of you're book on GitHub pages is a random one, so you might consider using a custom URL. -- Both GitLab and GitHub allow for extensive options for visibility of the source code. The TU Delft GitLab requires SSO login for editing the book. Although this is useful for TU Delft employees, it limits the collaboration with people outside of TU Delft. -- GitHub has a nice integration with the [GitHub Desktop application](git-setup_local.md). For GitLab it works as well, but has less functionality. -- [Utteranc.es](../basic-features/utterances.md) requires a GitHub repository to host the discussions. If you're using a GitLab repository, you need a separate GitHub repository and the discussions and book content is not at the same place. +#### Book URL +Github allows you to host your book on the GitHub server using GitHub pages (to be recognized by the `.github.io/` url, for example the [template book](https://teachbooks.github.io/template/)), which takes all the steps of hosting out of your hands. If you're book is part of the [GitHub Enterprise TU Delft](https://github.com/enterprises/tudelft) and is using SSO, a random url is generated `.github.io/`. Next to GitHub-provided URLs, you can set up a custom owned URL, although this requires some additional skills on a domain which you should own. -If you have doubt about this choice, we advise you to start on GitHub. Moving/duplicating your content to GitLab or hosting to a custom URL is always possible at a later stage. +On TU Delft's GitLab you need a webserver, which is offered by TeachBooks (to be recognized by the url `teachbooks.tudelft.nl/`, for example [this manual](https://teachbooks.tudelft.nl/jupyter-book-manual)) as the TU Delft OIT team (to be recognized by the url `interactivetextbooks.tudelft.nl/`, for example [the TU Delft OIT demo book](https://interactivetextbooks.tudelft.nl/open-textbooks-demonstration/)). +#### Real-time editing book +Editing the book can happen both locally as online on GitHub/GitLab. If done locally, the book can be generated and viewed locally too (typically takes around 1 minute) but this requires you to be at least user type 4 or 5 depending on the book content. The built book can also be viewed online separate from the released version. + +On GitHub we developed a [automatic process which builds the book and publishes it online](../external/deploy-book-workflow/README.md) in a very flexible way (publication of multiple version of the book, insights in book building errors, parallel so fast build, custom urls in subdirectories). + +On GitLab both we and other people at TU Delft have a more simplistic workflow which can be used when you're set up on those Git environments and webservers. If you want to use GitLab but still want to make use of the GitHub workflow, you can [mirror your repository to GitHub](https://docs.gitlab.com/ee/user/project/repository/mirror/push.html#set-up-a-push-mirror-from-gitlab-to-github). For the TU Delft OIT webserver you’re required to publish your book more officially, it cannot be used for viewing your book online in an active editing-phase since constant copyright checks have to be performed. + +#### Setting up book repository and website +On GitHub you can start right away with a git environment and online book using our [template](../external/template/README.md). + +On GitLab you can set up your own git environment, but you need to be given access by [TeachBooks](mailto:teachbooks@tudelft.nl) or [TU Delft OIT](mailto:Interactive-textbooks@tudelft.nl) to view your build book online. + +#### Book access with SSO +When you’re releasing your book on a server on which you're in control (connected to GitLab or GitHub), you can set up SSO login for visitors of the website. This can be arranged for on the TeachBooks server. + +If you want the same functionality with GitHub pages, your book should be part of the [GitHub Enterprise of TU Delft](https://github.com/enterprises/tudelft). This SSO login is a bit different as you're required to give access to specific accounts. Furthermore, the url of you're book on GitHub pages is a random one, so you might consider using a custom URL. + +#### Access to source code + +Both GitLab and GitHub allow for extensive options for visibility of the source code, both private, public or internally. On GitHub, public allows for collaboration with anyone. For SSO login, your book should be part of the [GitHub Enterprise of TU Delft](https://github.com/enterprises/tudelft) + +The TU Delft GitLab requires SSO login for editing the book. Although this is useful for TU Delft employees, it limits the collaboration with people outside of TU Delft. + +#### Integration with GitHub Desktop +GitHub has a nice integration with the [GitHub Desktop application](git-setup_local.md). For GitLab it works as well, but has less functionality. + +#### Intergration with Utteranc.es +[Utteranc.es](../basic-features/utterances.md) requires a GitHub repository to host the discussions. If you're using a GitLab repository, you need a separate GitHub repository and the discussions and book content is not at the same place. + +#### Summary Here's a table summarizing the information: | | GitHub | GitLab | |--|----------|-------------| -| Website to view book online | GitHub pages (`.github.io/`), for TU Delft GitHub Enterprise with SSO a random URL (`.github.io/`), or custom url `./`> 🌐 | TeachBooks (`teachbooks.tudelft.nl/`) or TU Delft OIT (`interactivetextbooks.tudelft.nl/`) πŸŽ“ | +| Book url | GitHub pages (`.github.io/`), for TU Delft GitHub Enterprise with SSO a random URL (`.github.io/`), or custom url `./`> 🌐 | TeachBooks (`teachbooks.tudelft.nl/`) or TU Delft OIT (`interactivetextbooks.tudelft.nl/`) πŸŽ“ | +| Real-time book editing | Automated and flexible (multiple version of the book, building error insights, fast, custom urls) πŸš€ | Automated but simplistic (one or two versions, command-line interface) πŸ›΅ For TU Delft OIT: restricted adaptations because of copyright checks 🚫 | | Setting up book website | Immediate and automated with [template](../external/template/README.md) ⚑️ | Manual setup on personal webserver, or access required by TeachBooks or TU Delft OIT 🚧 | -| Updating book website | Automated and flexible (multiple version of the book, building error insights, fast, custom urls) πŸš€ | Automated but simplistic (one or two versions, command-line interface) πŸ›΅ | -| Student book access with SSO | Only available for GitHub pages on GitHub Enterprise of TU Delft ❌, optional with custom URL βœ… | Optional βœ… | +| Book access with SSO | Only available for GitHub pages on GitHub Enterprise of TU Delft ❌, optional with custom URL βœ… | Optional βœ… | | Access to source code | Private (if part of organization linked to educational account) /public / internally TU Delft (on GitHub Enterprise of TU Delft) πŸ‘₯ | Private / public (read-only) / internally TU Delft, editing requires requires SSO login πŸ‘₯ πŸ‘€ | | GitHub Desktop | Well integrated 😎 | Basic integration πŸ™‚ | -| Utteranc.es | Can be linked to same repository 🏷️ | Requires GitHub repository next to GitLab repository 🏷️🏷️| \ No newline at end of file +| Utteranc.es | Can be linked to same repository 🏷️ | Requires GitHub repository next to GitLab repository 🏷️🏷️| + +If you have doubt about this choice, we advise you to start on GitHub. Moving/duplicating your content to GitLab or hosting to a custom URL is always possible at a later stage. \ No newline at end of file