Am ținut recent o conferință, Valoarea în predare nu este conţinut este profesor
Principalul meu punct în acest sens este:
Materialele dvs. de curs ar trebui să fie disponibile în public gratuit online.
Pentru a sprijini acest lucru, această postare de blog trece prin detaliile tehnice pe care le notez într-unul dintre diapozitivele mele: Cum să-ți pui cartea de curs online.
- Faceți o carte quarto
- Adăugați o licență corespunzătoare CC BY-NC-4.0
- Poate partaja/adapta, trebuie să atribuie
- Nu se pot folosi materiale în scopuri comerciale
- Adăugați un README
- Pune-l pe github
- Puneți-o să fie redată ca o carte online atunci când faceți modificări
Am făcut un repo pe github „șablon-carte-curs” care detaliază fiecare dintre acești pași.
Documentele quarto despre începerea unei cărți sunt excelent așa că aș recomanda să începeți de acolo: https://quarto.org/docs/books/#quick-start.
Dar, în esență, alergi:
quarto create project book .
Apoi vă va ghida prin crearea unui titlu etc
angajarea de a adăuga cartea
Este important să iei licența din timp. Acest lucru vă ajută să vă protejați munca și, de asemenea, le explică celorlalți cum să vă referiți și să vă utilizați. Personal, îmi place CC BY-NC-4.0, aceasta vă oferă următoarele condiții:
- Poate partaja/adapta, trebuie să atribuie
- Nu se pot folosi materiale în scopuri comerciale
Rețineți că acest lucru este diferit de CC-BY foarte comun, care permite utilizarea comercială.
Dacă nu sunteți sigur despre licențele pentru scopul dvs., ar fi util să verificați selectorul de aici https://creativecommons.org/chooser/
Folosind aceasta, am descoperit o altă licență utilă, CC-BY-NC-SA 4.0, care se bazează pe CC-BY-NC, dar cu o clauză suplimentară:
ShareAlike – Dacă remixați, transformați sau construiți pe baza materialului, trebuie să vă distribuiți contribuțiile sub aceeași licență ca și originalul.
Acest lucru este uneori cunoscut sub numele de „copyleft”. Acest lucru este uneori considerat prea restrictiv. Consultați-vă comunitatea despre care sunt standardele. Un alt loc util pentru a citi despre licențe este capitolul „licențiere” din cartea pachetelor R de Hadley Wickham și Jenny Bryan
Adaug un fișier LICENȚĂ și, de asemenea, un capitol license.qmd, precum și adaug licența la README.
angajarea de a adăuga licența
Cred că merită să adăugați câteva secțiuni cheie la fișierul README:
- Detalii: ca abstractul – cârligul!
- Cerințe preliminare: Ce vă așteptați să știe cursanții?
- Rezultatele învățării: Ce vor pleca știind?
- Program: O schiță a fiecărei ore de învățare, opțional cu un orar
commit de adăugare a README
Cursul tău ar trebui să trăiască într-un loc public! Puteți vedea, de exemplu, materialele noastre de curs aici: https://github.com/njtierney/course-book-template
Puteți folosi acțiunile github pentru a reda cartea. Acest lucru este cu adevărat îngrijit și înseamnă că cartea dvs. va fi redată de fiecare dată când faceți modificări. Înseamnă că nu trebuie să împingeți HTML, ci doar fișierele quarto.
Există câteva moduri diferite în care puteți gestiona acest lucru, se întâmplă să îmi placă folosirea paginilor Github.
Există câteva instrucțiuni foarte frumoase pe site-ul web quarto despre cum să configurați pagini github – https://quarto.org/docs/publishing/github-pages.html#github-action
Cu toate acestea, am găsit o configurație ușor diferită, pe care o voi împărtăși aici.
Aceasta implică utilizarea unui fișier DESCRIPTION pentru a urmări pachetele R pe care le utilizați. Motivul pentru care trebuie să facem acest lucru este să ne asigurăm, atunci când redăm cartea noastră, că toate pachetele R de care avem nevoie sunt instalate. Probabil că există și alte moduri în jurul acestui lucru și mi-ar plăcea să le aud, dar asta este ceea ce am găsit funcționează.
Iată primul pas în care adaug o dependență, în acest caz, tidyverse.
commit de a adăuga acest cod tidyverse
Apoi adăugați fișierul DESCRIPTION cu:
usethis::use_description(check_name = FALSE)
Apoi l-am editat pe al meu să arate așa:
Package: course-book-template
Title: A book about some things
Version: 0.0.0.9000
Authors@R:
c(
person(
given = "Nicholas",
family = "Tierney",
email = "(email protected)",
role = c("aut", "cre"),
comment = c(ORCID = "https://orcid.org/0000-0003-1460-8722")
)
)
Description: Course materials for your topic. This should have two sentences.
License: CC-BY-NC 4.0 + file LICENSE
Encoding: UTF-8
Language: en-GB
Roxygen: list(markdown = TRUE)
RoxygenNote: 8.0.0
comite
Puteți adăuga apoi dependența de pachet în Imports sau Depends. Pe care îl folosiți este în mod normal foarte important pentru dezvoltarea pachetului R, dar motivul pentru care folosim un fișier DESCRIPTION aici este pentru a urmări dependențele noastre.
usethis::use_package("tidyverse", type = "Depends")
comite
Apoi adaug acțiunile github – de fapt, vă puteți referi doar la un fișier, așa că va funcționa:
use_github_action(url = "https://github.com/njtierney/gentlegit/blob/main/.github/workflows/quarto-publish.yml")
Acest lucru vă va oferi un mesaj ca următorul:
✔ Creating .github/. ✔ Adding "^\.github$" to .Rbuildignore. ✔ Adding "*.html" to .github/.gitignore. ✔ Creating .github/workflows/. ✔ Saving "njtierney/gentlegit/.github/workflows/quarto-publish.yml@main" to .github/workflows/quarto-publish.yml.
comite
De asemenea, probabil este un moment bun pentru a adăuga un fișier .gitignore. Aceasta este o idee bună pentru a vă asigura că nu scrieți fișiere HTML (pot fi foarte mari și nu avem nevoie de ele) sau alte tipuri de fișiere care ar putea fi cu adevărat mari sau care conțin informații sensibile în ele.
usethis::use_git_ignore("*.pdf")
Va crea fișierul și îi va spune lui git să nu comite niciodată un PDF.
Editez fișierul meu .gitignore astfel încât să arate așa:
/.quarto/ **/*.quarto_ipynb .Rproj.user .Rhistory .RData .Ruserdata dev docs /.quarto/ *.aux *.log *.pdf *.tex *.toc *.rds *_files *_cache *.html .DS_Store
comite
Odată ce toate acestea sunt spuse și făcute, va trebui în continuare să rulați câteva comenzi în terminalul dvs.:
quarto publish gh-pages
Acest lucru ar trebui să producă o întrebare de genul:
nick course-book-template(main) > quarto publish gh-pages ? Publish site to https://njtierney.github.io/course-book-template/ using gh-pages? (Y/n) ›
raspunde „Y”
Veți obține apoi un cod care arată astfel:
Switched to a new branch 'gh-pages' (gh-pages (root-commit) 8ccc5e0) Initializing gh-pages branch remote: remote: Create a pull request for 'gh-pages' on GitHub by visiting: remote: https://github.com/njtierney/course-book-template/pull/new/gh-pages remote: To https://github.com/njtierney/course-book-template.git * (new branch) HEAD -> gh-pages Switched to branch 'main' Your branch is up to date with 'origin/main'. From https://github.com/njtierney/course-book-template * branch gh-pages -> FETCH_HEAD
Și apoi un cod de randare care va arăta astfel:
Rendering for publish: (1/4) index.qmd (2/4) intro.qmd processing file: intro.qmd 1/3 2/3 (unnamed-chunk-1) 3/3 output file: intro.knit.md ... (|) Deploying gh-pages branch to website (this may take a few minutes)
Așteptați câteva minute, așa cum vă cere.
Atunci ar trebui să vezi ceva de genul:
(✓) Deploying gh-pages branch to website (this may take a few minutes) (✓) Published to https://njtierney.github.io/course-book-template/ NOTE: GitHub Pages deployments normally take a few minutes (your site updates will be visible once the deploy completes)
Site-ul dvs. web probabil nu va fi vizibil încă, ceea ce pare un pic enervant, dar îl puteți urmări pe fila „acțiuni”, de exemplu, https://github.com/njtierney/course-book-template/actions
Odată ce s-a aprins verde (sper că a făcut-o!)
Ar trebui să accesați secțiunea „despre” și să faceți clic pe roata de setare:
Există mai multe lucruri pe care le puteți face, cum ar fi configurarea propriului site web personalizat în loc să utilizați github.
Deci, în loc de https://njtierney.github.io/course-book-template/, ați putea avea: „course-book-template.com”.
Și asta este!