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. 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ř. ./courses/content/index.html.
    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>

Pokud je soubor příliš velký (> 10 MB), preferujte jeho nahrání na Teams (resp. SharePoint) a na HelpFIT pouze sdílet odkaz. Umístění, do kterého soubor nahráváte, musí být pod kontrolou oddělení ICT.[4]

AsciiDoc

  1. Každá stránka musí mít právě jeden titulek – nadpis první úrovně [5].
  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.[6]
  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[7] 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.[8]

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.[9]

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.[10]

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. Ideálně volit Team-FIT.
  5. = Title v AsciiDocu.
  6. Hlavně nezalamovat text na fixní počet znaků!
  7. https://en.wikipedia.org/wiki/Don%27t_repeat_yourself
  8. Poslední čtyřčíslí je telefonní číslo v rámci interní sítě.
  9. Typicky pro odkazy.
  10. Typicky pro porty dané služby atp.