Skip to content

Rewrite the guides to Markdown #450

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Rewrite the guides to Markdown #450

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d336fd0
Enable definition lists and linkify extensions in the MyST parser
jsmitka Jul 18, 2025
7bfc6c8
Rewrite pages under `docs/guides` to Markdown using MyST syntax
jsmitka Jul 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 ---------------------------------------------------


Expand Down
301 changes: 301 additions & 0 deletions docs/guides/beginners-course.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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ý.
Loading