Návody FIT
Jdi na navigaci

Přispívání

HelpFIT je tvořen s využitím PagesFIT, AsciiDoc a modifikované verze generátoru course-pages.

FAQ

Nalezl/a jsem chybu
Lze využít jeden ze dvou způsobů:
  1. Nahlášení chyby (více viz Vytvoření issue) prostřednictvím tlačítka Nahlásit chybu v horní části obrazovky.
  2. Navržení úpravy prostřednictvím vlastního merge requestu.
Mám návrh na zlepšení
Stejné jako při hlášení chyby.
Chci přidat vlastní návod

V současné době je politikou HelpFIT prezentovat návody ke službám výhradně v režii oddělení ICT tak, aby bylo možné ručit za jejich platnost a správnost. Všem osobám spojeným s FIT ČVUT je k dispozici služba PagesFIT, na které tato stránka stojí. Kdokoliv (např. i katedra nebo výzkumná skupina atp.) má možnost si vytvořit vlastní stránky, plně ve své režii.

Pochopitelně je možné se spojit s oddělením ICT ohledně dalšího postupu prostřednictvím helpdesk formuláře. Případně váš požadavek eskalujte prostřednictvím vedoucího oddělení/katedry.

Konvence

Pro práci jsou doporučeny následující nástroje:

  • (preferováno) Lokální vývoj s využitím VSCode a course-pages generátoru. Součásti projektu je i doporučené prostředí, které mimo jiné obsahuje i spell check.
  • GitLab web editor s náhledem. Tento náhled nemusí být přesný.

Struktura

  1. Pojmenování souborů
    1. pokud možno anglicky,
    2. malými písmeny,
    3. slova oddělovat spojovníkem (-),
    4. v názvu souboru se nesmí vyskytovat mezery.
  2. Návody v kořenové úrovni umisťovat do složek.[1]
  3. Každý textový soubor by měl končit právě jedním prázdným řádkem.
  4. Na FAQ vždy používat samostatný soubor s titulkem Často kladené otázky a názvem faq.adoc, využívejte makro qanda.
  5. Každý návod musí obsahovat sekci Podpora ve které budou uvedeny kontakty na koho se obracet v případě potíží nebo nápadů na zlepšení.[2] Pro tuto sekci lze využít Ustálené výrazy.

Snímky

  1. Používat white mode a českou lokalizaci, pokud je to možné.
  2. U názvu snímku používat suffix ve tvaru .<lokalizace>, například snimek-01.cs.png
  3. U snímků obrazovky preferovat formát PNG.
  4. V ideálním případě fotit celé okno, viz např. Přidání účtu.
    1. Za tímto účelem lze ve VSCode projekt spustit. Dojde tak ke spuštění čisté konfigurace Google Chrome.
  5. Jako ukázkového uživatele využívat fiktivní osobu Kevin Flynn
    1. flynnkev@cvut.cz, více viz Tron.

    2. Pro případ, že potřebujete uvést obrázek QR kódu, lze využít následující:

      qr example
  6. Za účelem zrychlení běhu generátoru, snížení celkové velikosti stránky a zlepšení uživatelské přívětivosti je nutné provést kompresi médií.[3] Doporučená šířka je 1200 px, je však třeba zohlednit individuální případy, celkovou čitelnost atp. Maximální velikost obrázku by se měla držet v (ideálně nižších) desítkách kB. Je doporučeno využít ImageMagick. Více viz následující příkazy.
Ukázka 1. Kód pro kompresi s využitím ImageMagick
convert <nazev souboru> \
    -density 72 \
    -resize <velikost> \
    -alpha off \
    +dither \
    -colors 256 \
    -depth 8 \
    -strip \
    -define png:compression-filter=5 \
    -define png:compression-level=9 \
    -define png:compression-strategy=1 \
    -define png:exclude-chunk=all \
    -interlace none \
    <nazev souboru>
Ukázka 2. Kód pro kompresi snímků z macOS (alpha kanál)
convert <nazev souboru> \
  -density 72 \
  -resize <velikost> \
  -alpha on \
  +dither \
  -strip \
  -define png:compression-filter=5 \
  -define png:compression-level=9 \
  -define png:compression-strategy=1 \
  -define png:exclude-chunk=all \
  -interlace none \
  <nazev souboru>

Umístění, do kterého soubor nahráváte, musí být pod kontrolou oddělení ICT. Pokud je soubor příliš velký (> 10 MB), preferujte jeho nahrání na GitLab s využitím Git LFS, případně kontaktujte ICT oddělení pomocí helpdesk formuláře.

AsciiDoc

  1. Každá stránka musí mít právě jeden titulek – nadpis první úrovně [4].
  2. Pomlčky (nikoli spojovníky) psát buď pomocí -- (vykreslí se jako –), nebo přímo Unicode znakem –.
  3. Před nadpisem dva prázdné řádky, za nadpisem jeden prázdný řádek.
  4. Každá věta (souvětí) na samostatný řádek.[5]
  5. Používat atribut imagesdir.
  6. Uvozovky v běžném textu (ne kódu) psát buď „takto“ (vykreslí se: „takto“), nebo přímo pomocí Unicode znaků „takto“ (viz https://www.zoul.cz/uvozovky/).
  7. Využívejte makra btn:[] (1), menu:[] (2) a kbd[].
    1. Ukázka 1: Tlačítko
    2. Ukázka 2: Soubor › Uložit › Uložit jako.
    3. Ukázka 3: Ctrl+R.
  8. Pokud koliduje admonition blok s toc, využijte Kolize s obsahem stránky.
  9. U anglicismů je vhodné používat kurzívu.

Ustálené výrazy

Z důvodu zachování konzistence napříč návody a dodržování konceptu DRY[6] jsou využívány proměnné a některé ustálené výrazy.

Zkratky

U známých názvů v prostředí ČVUT (např. názvy součástí) je preferováno využití zkratek. Pokud autor považuje jako nutné zmínit celý název, je doporučeno tento název uvést a společně s ním i zkratku, pod kterou bude dále uváděn.

Názvy, které jsou referovány běžně zkratkou:

  • Místo České vysoké učení technické v Praze lze uvádět pouze ČVUT.
  • Místo Fakulta informačních technologií lze uvádět pouze FIT ČVUT.
  • Místo Výpočetní a informační centrum ČVUT v Praze lze uvádět pouze VIC ČVUT
  • a další.

Nadpisy

Konvence týkající se nadpisů:

  1. V nadpisech je doporučeno vyvarovat se obratům jako Jak se přihlásit. Místo toho je doporučeno psát pouze Přihlášení.
  2. Stejně tak je zbytečné psát sekci O systému jako první sekci. Místo toho je doporučeno tento systém rovnou popsat v prvních odstavcích, není nutno uvádět explicitně nadpis.

Časté výrazy

Časté výrazy:

  • Přihlaste se uživatelským jménem a heslem ČVUT.
  • …​ ve tvaru <username>@fit.cvut.cz
    • Je doporučeno ztučnit doménu, jelikož dochází k záměnám s doménou cvut.cz.
  • Používat e-mail namísto email nebo mail.
  • Telefonní čísla v rámci fakulty uvádět ve tvaru +420 12345 6789 tj. s předvolbou a poslední čtyřčíslí oddělit mezerou.[7]

Oslovení čtenáře

Je doporučeno vyvarovat se oslovením čtenáře a místo toho využívat neurčitý podmět (popř. uživatel) ve větě a trpný rod. Tj. místo V případě, že využíváte …​ píšeme V případě využívání …​.

Pokud je oslovení nutné, preferujte zájmenné tvary např. váš místo Váš (tj. malé V).

Globální proměnné

Uložení hodnoty do proměnné je vhodné např. pro hodnoty, které mohou v budoucnu být předmětem změny.

Upozornění:

Globální proměnné mají při kolizi názvů nejvyšší váhu a neumožňují vyhodnocení maker.

Definované v souboru course-pages.yml a jsou dostupné ve všech souborech zpracovávaných generátorem. Jejich využití je silně preferováno pro výrazy využívané napříč návody.[8]

Proměnné návodu

Uchovávané v souboru .vars.adoc v kořenové složce konkrétního návodu. Tento soubor je před vyhodnocením proměnné třeba includovat s pomocí include::../.vars.adoc[]. Jejich využití je preferováno pro údaje sdílené v rámci jednoho návodu.[9]

Lokální proměnné jsou definovány standardně s pomocí :promenna: 123 a vyhodnoceny pomocí {promenna}.

Sdílený obsah

Proměnné neumožňují práci s více-řádkovým obsahem. Pro tento účel je doporučeno využívat soubor .shared-content.adoc (globální nebo na úrovni návodu) viz následující příklad:

shared-content.adoc
// tag::sync[]
Mimo e-mail lze automaticky synchronizovat i přidružené služby Microsoft 365 jako jsou <<sync>>
// end::sync[]

// tag::outlook-recommendation[]
Pro plnou kompatibilitu doporučujeme využívat aplikaci *Microsoft Outlook*.
// end::outlook-recommendation[]
Využití v návodu
include::../.shared-content.adoc[tag=outlook-recommendation]

V případě využívání include a xref se uživatel může setkat s chybou při generování HTML. Tato chyba nevede k selhání, může však způsobovat zpomalování sestavení. Jedná se o známou chybu, viz Často kladené otázky.

Git

  1. Titulek commit zprávy psát v imperativu (např. „Add something“, ne „Added something“), s počátečním velkým písmenem, bez tečky na konci a pokud možno do 69 znaků (max 80 znaků).
    1. Jako prefix přidejte návod, kterého se změna týká. Např. projectsfit: Fix typo
  2. Nastavte si git user.name (více např. zde)
  3. V nejvyšší možné míře využívejte merge requesty. Pouze v případě hotfixů atp. je přípustné commitovat do master branch přímo.
  4. V případě, že vytváříte nový návod, je možné provést squash během mergování. V opačném případě je doporučováno zachovat jednotlivé commity, např. s využitím semi-lineární historie.
  5. Pokud změna v dané větvi souvisí s konkrétním issue v Jira, uvést kód issue v názvu větve. Např. ICT-1901-…​
  1. I pokud jde o návod o jednom souboru. ↩
  2. Ne vždy se jedná nutně o oddělení ICT. ↩
  3. V opačném případě může mít jedna stránky velikost v několika MB. ↩
  4. = Title v AsciiDocu. ↩
  5. Hlavně nezalamovat text na fixní počet znaků! ↩
  6. https://en.wikipedia.org/wiki/Don%27t_repeat_yourself ↩
  7. Poslední čtyřčíslí je telefonní číslo v rámci interní sítě. ↩
  8. Typicky pro odkazy. ↩
  9. Typicky pro porty dané služby atp. ↩