Imported from helenvellau-netizen/andmeinseneeria-uus (AGENTS.md). Install upstream with npx skills add helenvellau-netizen/andmeinseneeria-uus. Copyright stays with the author.

AGENTS.md

Juhised HARNO andmeinseneride täiendkoolituse praktikumimaterjalide loomiseks.

Tasemepõhised juhised on eraldi failides:

• AGENTS_BAASTASE.md — baastaseme materjalid
• AGENTS_EDASIJOUDNUD.md — edasijõudnute materjalid

Kursuse kontekst

• HARNO andmeinseneride täiendkoolitusprogramm, 13 nädalat, 12 EAP.
• Kaks rühma: algajad ja edasijõudnud. Ühised teisipäevased loengud, eraldi neljapäevased praktikumid.
• Õpe toimub töö kõrvalt: loengud, praktikumid, iseseisev töö. Materjalid peavad toimima ka Moodle'is iseseisvaks kordamiseks.
• Materjalid jaotatud kaustadesse baastase/ ja edasijoudnud/. Kui tase ei selgu, eelda baastaset.
• Mooduli juurkausta README.md kirjuta tasemeneutraalselt.

Keel ja stiil

• Kirjuta loomulikus, korrektses eesti keeles. Lühikesed, selged laused.
• Üks põhiidee lauses. Pane olulisim lause algusesse.
• Eelista tegusõnu nimisõnalistele konstruktsioonidele ja omasõnu võõrsõnadele, kui sisu ei kannata.
• Ingliskeelne termin: esmamainimisel lisa eestikeelne selgitus. Kasuta läbivalt samu termineid.
• Väldi: bürokraatlikku sõnastust, põhjendamata žargooni, täitesõnu, turunduslikku paisutust.
• Väldi pisendavat tooni ("lihtne", "ilmselge", "nagu kõik teavad").
• Toon on toetav ja rahulik, aga mitte udune ega jutukas.

Uute mõistete selgitamine

1. Alusta probleemist, mida mõiste lahendab.
2. Anna lühike definitsioon lihtsas keeles.
3. Too konkreetne näide.
4. Alles siis mine tehnilise detaili juurde.
5. Mitme mõiste korral selgita omavaheline seos.
6. Kui samm eeldab varasemat teadmist, meenuta see lühidalt.

Praktikumi juhendi struktuur

1. Eesmärk
2. Õpiväljundid
3. Eeldused (sh keskkond ja vajalikud teenused)
4. Miks see teema on oluline
5. Uued mõisted
6. Samm-sammuline praktikumi käik
7. Kontrollpunktid ja oodatavad vahetulemused
8. Levinud vead ja nende lahendused
9. Kokkuvõte
10. Valikuline lisaharjutus

Koodi ja käskude juhised

• Kõik käsud ja koodinäited peavad olema kopeeritavad.
• Kasuta selgeid faili-, tabeli- ja muutujanimesid.
• Ütle, millises keskkonnas (konteiner, host, veebirakendus) sammud tehakse.
• Kui samm sõltub varasemast seadistusest, nimeta see jaotises "Eeldused".
• Enne või kohe pärast koodiplokki selgita, mida see teeb.
• Anna vihje, milline väljund kinnitab, et samm õnnestus.
• Kui samm on veale tundlik, lisa kohe tõrkeotsing.

Kvaliteedikontroll enne üleandmist

• Kas valitud taseme õppija saab aru, mida ta igas sammus teeb ja miks?
• Kas uued mõisted on selgitatud?
• Kas juhendit saab kasutada ilma juhendaja suulise lisaselgituseta?
• Kas iga sammu juures on arusaadav oodatav tulemus?
• Kas komistuskohad on ennetatud?
• Kas maht ja tempo on realistlikud?
• Kas faili- ja kaustaviited vastavad repo struktuurile?

Vaikimisi tööreegel

Kui kasutaja palub luua praktikumi juhendi:

1. Määra tase (kasutaja soov, sihtkaust, olemasolev materjal). Vaikimisi: baastase.
2. Loe vastavat tasemefaili (AGENTS_BAASTASE.md või AGENTS_EDASIJOUDNUD.md).
3. Kirjuta juhend selle faili juhiste järgi.