Rewrite the guides to Markdown

docs/conf.py

@@ -145,6 +145,16 @@
 sphinxemoji_source = "twemoji.min.js"
 
 
+# -- Options for the MyST extension ------------------------------------------
+# Available options are described in the docs:
+#   https://myst-parser.readthedocs.io/en/v0.15.1/sphinx/reference.html
+myst_enable_extensions = [
+    "dollarmath",
+    "deflist",
+    "linkify",
+]
+
+
 # -- Setting up extensions ---------------------------------------------------
 
 

docs/guides/beginners-course.md

@@ -0,0 +1,301 @@
+# Jak pořádat kurz pro začátečníky
+
+Tato příručka popisuje, jak pořádáme [začátečnické kurzy PyLadies](https://pyladies.cz/course.html),
+zhruba tříměsíční bezplatný kurz s každotýdenními dvouhodinovými setkáními.
+
+Podobné principy by měly fungovat i kdekoliv jinde.
+Můžeš to tu brát jako návod nebo jako inspiraci,
+nebo něco mezi tím – je to jen na tobě!
+
+```{warning}
+Tato příručka ještě není úplně kompletní.
+```
+
+```{image} ../_static/images/pylady.svg
+:width: 20%
+:align: center
+``` 
+
+
+## Před začátkem
+
+Než může kurz začít, potřebuješ místo, čas, mentory, účastníky, a obsah.
+Pokud rozjíždíš pilotní kurz v novém městě a bez dosavadních zkušeností, na první běh ti stačí sehnat
+cca 15 účastníků a 3 kouče. Nebo pokud se ti naskytne jen menší prostor pro méně lidí, klidně spusť první
+kurz v komornějším počtu lidí. Získáte zkušenosti a na druhý pokus už v klidu zvládnete větší skupinu.
+
+
+### Čas
+
+Jak často chceš učit?
+
+> Nám se vyplatilo se sejít jednou za týden.
+> Intenzivní kurzy mohou být i častěji, ale je složitější sehnat dobrovolníky.
+> Méně časté lekce nedoporučujeme, pokud neexistuje doplňující program
+> (např. úkoly online).
+
+Kdy to bude?
+
+> Nám se osvědčily kurzy večerní, ve všední dny od 17:00 nebo 18:00. Jedna lekce trvá dvě hodiny.
+> Chceš-li nalákat pracující nebo studující, je to asi jediná reálná možnost.
+> Snažíme se obvykle vybrat jiný den než pátek a vyhýbáme se pokud možno státním svátkům.
+> Obvykle děláme kurzy jarní a podzimní, takže vynecháváme letní měsíce a povánoční období.
+
+Jak dlouho?
+
+> Každá lekce našeho kurzu trvá dvě hodiny.
+> Po dvou-třech hodinách začíná být člověk unavený a učení už nejde tak dobře.
+> Aktuální podoba kurzu vychází zhruba na 3 měsíce, ale délka se dá nastavit podle lokálních možností.
+
+
+### Účastníci
+
+Kolik lidí chceš kurzem provést?
+
+> Naše začátečnické kurzy jsou pro zhruba 25 lidí.
+> Počítej s tím, že pokud je kurz zadarmo, budou lidi postupně odpadávat
+> – např. se jim změní pracovní situace, nebo jednoduše zjistí, že
+> programování není pro ně.
+> Klidně se může stát, že z 25 lidí celým kurzem projdou 3.
+
+Jaká je cílová skupina?
+
+> Není začátečník jako začátečník.
+> Chceš (jako my) učit lidi, kteří vůbec neumí progrmovat,
+> nebo ty kteří přicházejí z jiného jazyka?
+> Chceš učit vědce? Učitele? Testery? Středoškoláky?
+> Každé omezení cílové skupiny ti umožní kurz lépe přizpůsobit.
+>
+> Je dobré když má každý účastník svůj laptop, který pak používá
+> i mimo lekce.
+
+
+### Místo
+
+Podle toho, kolik plánuješ účastníků, vyber vhodné prostory.
+Potřebuješ prostor s wifi a projektorem.
+
+Sponzorované prostory
+
+> Pro komunitní kurz je dobré se zeptat IT firem, jestli by neposkytly na
+> večer zasedačku. Místo mají občas i školy či studentské unie, univerzity, knihovny.
+
+Placené prostory
+
+> Placené kurzy (nebo lépe, kurzy s nenulovým rozpočtem) se dají pořádat
+> v coworkingovém centru nebo školícím středisku.
+> Možností je spousta.
+
+
+### Mentoři
+
+Hlavní kouč
+
+> Na každé lekci by měl být jeden „hlavní kouč”, který lekci řídí
+> a zná příslušné materiály.
+> Materiály jsou prověřené praxí, hlavní kouč se jich samozřejmě nemusí držet doslovně,
+> ale neměl by bez předchozí konzultace či praxe úplně opouštět osvědčenou koncepci lekce.
+> Je dobré, když funkci hlavního kouče po celé trvání kurzu zastává ten stejný
+> člověk, který má pak přehled o tom, co se probralo.
+> Pokud se hlavní koučové střídají, měl by každou lekci vést někdo, kdo
+> byl minimálně na lekci předchozí.
+
+Vedlejší koučové
+
+> Ostatní mentoři pomáhají (např. rozdávají papírové materiály),
+> a hlavně řeší konkrétní problémy.
+> V téhle roli nemusí být všichni experti. Naopak, pro účastníka
+> předchozího „běhu” začátečnického kurzu je koučování skvělá příležitost
+> jak si všechno zopakovat, a zjistit kolik se toho naučil :)
+> 
+> Doporučujeme zhruba jednoho vedlejšího kouče na 3-5 účastníků.
+> Ze začátku, na instalaci a nastavení prostředí, je lepší jich pozvat spíš
+> víc; potom nebývá problém když občas někdo odpadne.
+> 
+> Koučové se dají nabrat na srazech, případně se dají oslovit programátoři
+> v okolních firmách. Není problém, pokud vedlejší kouč v praxi Python nepoužívá.
+> Určitě koučování nabídni i účastníkům předchozích kurzů.
+> V první řadě, látku uslyší znovu a tím si ji oživí. A navíc vysvětlováním a pomáháním s chybami účastníků jim i leccos zpětně dojde.
+> Tuto metodu i samotní programátoři používají při své práci a jde o tzv. [Rubber duck debugging](https://en.wikipedia.org/wiki/Rubber_duck_debugging).
+> 
+> Spousta stávajících koučů PyLadies je ochotná jednorázově vypomoci a přijet
+> do jiného města
+
+
+### Obsah
+
+Naše materiály jsou [volně k použití](https://pyladies.cz/course.html)
+pod licencí [CC-BY-SA](https://creativecommons.org/licenses/by-sa/4.0/), a dají se použít přímo nebo upravit přesně podle
+vašich představ :)
+
+
+## Rozvrh
+
+Vyber si den D, kdy má kurz začít.
+Podle toho si vytvoř časový rozvrh, ať na nic nezapomeneš:
+
+* D - 2 měsíce
+
+  > * Začít shánět kouče (pokud je už nemáš potvrzené)
+  > * Sehnat a domluvit prostory
+  > * Dej vědět organizátorkám PyLadies na [email protected], pomůžou ti s propagací mezi
+  >   potenciální kouče a účastnice
+
+* D - 1 měsíc
+
+  > * Zveřejnit přihlašovací formulář.
+  > 
+  >   (XXX: Odkaz na vzorovou přihlášku)
+
+* D - 2 týdny
+
+  > * Vybrat účastníky
+  > 
+  >   > * Vybraným poslat mail s radostnou zprávou
+  >   > * Zhruba pět až deset odmítnutých informovat, že jsou náhradníci
+  >   > * Ostatní odmítnutým sdělit že se bohužel nevejdou
+  > * Informovat kouče
+  > 
+  > (XXX: šablony na tyhle maily)
+
+* D - 1 den
+
+  > * Poslat účastníkům připomínací mail
+
+* D + zhruba 3 měsíce
+
+  > * Plánovaný konec kurzu
+
+
+## Tabulka koučů
+
+Je vhodné si připravit tabulku, kterou lze všem koučům nasdílet online a mohou v ní současně upravovat kdy který z nich může na lekci přijít. Nám se při organizování kuzů vyplatilo používání Google Tabulek, které lze nastavit na přístup na konkrétní e-mailové adresy či jen i anonymnim osobam, které mají odkaz. Koučové tak nutně nemusí mít Gmail, dají si odkaz někam, kde ho budou mít na očích a organizace se tím velmi zjednodušuje.
+
+
+### Příklad takové tabulky
+
+| Datum        | Název lekce  | Poznámka k lekci    | Hlavní kouč  | Vedlejší kouč | Vedlejší kouč | Vedlejší kouč | Vedlejší kouč |
+|--------------|--------------|---------------------|--------------|---------------|---------------|---------------|---------------|
+| 02.03.  2028 | Instalace    | potřeba více koučů  | Hugo         | Jarda         | Evžen         | Jana          | Emilka        |
+| 09.03.  2028 | První program| ukázat dpaste.com   | Hugo         | Emilka        | Jana          |               | Pavla         |
+| 16.03.  2028 | Cykly        |                     | Jana         | Emilka        |               | Evžen         |       X       |
+| 23.03.  2028 | Git          |                     | Hugo         | Emilka        | Jan Tleskač   |     X         |       X       |
+
+**Jarda vidí, že na 9.3. a 16.3. bude potřeba pokaždé ještě jednoho kouče a tak ví, že může pomoci a napíše se tam - plánování vidí všichni a ne jen organizátor, což mu usnadní práci a může se věnovat dalším věcem! Někdy není potřeba koučů tolik, můžeš jim to dát vědět domluveným znakem. V naší tabulce je to X**
+
+
+## První lekce
+
+První lekce je u nás jiná než ostatní: je potřeba všechno nainstalovat
+a nastavit (Python, Git, editor, virtualenv).
+To se na každém počítači dělá jinak, a každému to trvá jinak dlouho.
+(Dá se říct že cíl první lekce je, aby po ní fungovaly všechny počítače stejně.)
+
+Proto doporučujeme první lekci kromě úvodní prezentace neřídit centrálně,
+ale nechat účastníky, aby (s pomocí koučů) všechno nainstalovali podle
+instrukcí na internetu.
+
+Součást první lekce je i seznámení s příkazovou řádkou (která je pak potřeba
+k nastavení virtuálního prostředí).
+
+V rámci úvodní prezentace by mělo padnout:
+
+> * Trocha historie
+> * Co se naučíme, a co naopak v kurzu nebude
+> * Instrukce pro účastníky – viz barevné papírky níže
+> * Pár instrukcí pro kouče
+> * Představení koučů i účastníků ( je dobré, pokud mohou účastníci kurzu uvést, proč na kurz přišli a co jaká bližší oblast je zajimá. Celé oboustranné představování většinout dost prolomí ledy a kurz budí přátelský dojem)
+> * Co je dobré taky zmínit - viz seznam
+
+(usb_flash)=
+
+Je dobré mít několik flashek s následujícíma věcma, aby je všichni nestahovali
+najednou:
+
+> * Aktuální kopie materiálů
+> * Instalačky Pythonu (Windows 64-bit, Windows 32-bit, macOS)
+> * Instalačky Atomu (Windows, macOS)
+> * Instalačky Gitu (Windows 64-bit, Windows 32-bit, macOS)
+
+
+Systém barevných papírků
+------------------------
+
+Osvědčil se nám „papírkový” systém převzatý ze [Software Carpentry](https://software-carpentry.org/).
+
+Každý účastník má k dispozici 3 barevné lepící papírky: žlutý, zelený a červený [^f1].
+
+Na *žlutý* papírek napíše své jméno (nebo přezdívku), a nalepí ho *vedle*
+počítače – tak, aby koučové na jméno viděli, když přijdou pomoct.
+
+*Červený* papírek si účastník nalepí na počítač, když potřebuje pomoc,
+když něco nebylo vysvětleno dost jasně, nebo když se něco pokazilo.
+Papírek by měl přesahovat horní okraj obrazovky, aby byl vidět odkudkoli.
+
+*Zelený* papírek si naopak účastník nalepí na počítač, když je hotový
+s aktuálním úkolem.
+(Což neznamená že se nudí – může zkusit nějaký vlastní experiment, nebo pomoci
+ostatním.)
+
+Koučové sledují místnost.
+Když vidí červený papírek, hbitě přiskočí, vysvětlí nejasnosti a vyřeší problém.
+Když červený papírek nevidí, jdou pomáhat někde, kde ještě nevidí papírek
+zelený.
+
+V momentě kdy je všude „zeleno” (kromě případných větších problémů, kde
+pomáhá kouč) hlavní kouč požádá o sundání papírků, a lekce pokračuje dál.
+
+Na konci lekce dostanou papírky další roli: na zelený papírek každý účastník
+napíše něco, co se mu líbilo, a na červený něco negativního.
+Hlavní kouč pak papírky vybere, aby měl představu co v příští lekci
+zlepšit.
+(Doporučuji sepsat shrnutí a reakci, jako např. [tady](https://pyladies.cz/v1/notes/2016-brno-jaro/2016-03-14.txt))
+
+
+## Program lekce
+
+Každá lekce (kromě té první) je u nás rozdělena do dvou částí:
+
+* 30 minut: kontrola domácích úkolů
+
+  > Varianta A: Účastníci se rozdělí do dvojic. Jeden z nich vybere úkol, který byl zajímavý,
+  > vtipný, jednoduchý, nebo jinak pozitivní, a vysvětlí řešení.
+  > Pak je řada na druhém ze dvojice.
+  > Potom stejným způsobem proberou dva úkoly, které byly složité, nebo se je
+  > nepodařilo vyřešit. (Když řešení nezná ani jeden, pomůže kouč.)
+  > 
+  > Varianta B: Vytvoří se menší skupinky s koučem. Např. 3-5 účastníků a kouč a úkoly projdou spolu, podívají se na různá řešení úkolů
+  > každého z účastníků. Zde je důležité, že kouč by měl být
+  > v takové skupině aktivní víc než u variaty A, kde čeká, až jej někdo požádá o pomoc.
+
+* 90 minut: probírání nového materiálu
+
+  > V rámci celého kurzu je dobré namixovat neinteraktivní „přednášky” (vhodné
+  > na vysvětlení konceptů), úkoly k řešení (pro osvojení materiálu),
+  > a „live coding”, kdy kouč vysvětluje přímo na vznikajícím programu
+  > (tady se např. ukáže, že opravdu každý dělá chyby – a jak takové chyby
+  > najít a vyřešit).
+
+
+## Pravidla chování pro kouče
+
+Každý vedlejší i hlavní kouč by měl mít na paměti jistá pravidla, aby kurz nepůsobil zmateně a každému účastníkovi se dostalo stejné pomoci. Pro příklad jsme jich pár zkusili a velmi se nám jejich prosazování vyplatilo.
+
+> * klávesnice každého účastníka je svatá a psát na ní může jen on sám
+> * mluví pomalu a má trpělivost, s úsměvem je vše lepší a lekce budí přátelský dojem
+> * vždy vysvětluje pouze to, co se aktuálně řeší (platí především pro vedlejší kouče), nezdržuje lekci vysvětlováním látky dopředu (to
+>   je úkol hlavního kouče)
+> * nekempuje u jednoho účastníka celou lekci, ale snaží se podávat pomoc mezi více účastníky
+> * řešení problému by mělo vzejít od účastníka, vedlejší kouč se jej na řešení snaží navést otázkami, na které účastník sám odpovídá (
+>   přímé odhalení řešení pomůže účastníkovi pouze krátkodobě)
+> * snaží se nepoužívat terminologii, kterou účastník zatím nezná
+> * nezlehčuje problémy, které účastník řeší ani je nevhodně nekomentuje, nevzdychá a vyvaruje se demotivujícím hláškám
+
+
+## Pokračovací a doprovodné srazy
+
+XXX: "čtvrteční srazy"
+
+
+
+[^f1]: Červený papírek nemusí být přímo červený; stačí když je *červenější* než ten žlutý a zelený.