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ů:

Nahlášení chyby (více viz Vytvoření issue) prostřednictvím tlačítka Nahlásit chybu v horní části obrazovky.
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

Doporučené nástroje

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

Textový editor VSCode nebo VSCodium s rozšířením AsciiDoc.
Jakékoliv IDE od JetBrains s pluginem AsciiDoc nebo AsciiDoc Pro.
GitLab web editor s náhledem. Tento náhled nemusí být přesný.
Course Pages generátor pro lokální prohlížení vygenerovaných stránek.

Struktura

Struktura návodů se řídí následujícími pravidly:

Podle jazyka návodu se návody (a soubory k němu patřícím) rozdělují do /cs a /en složek v kořeni repozitáře.
Každý návod je umístěn ve vlastní složce pojmenované podle názvu návodu.
Každý návod obsahuje úvodní stránku index.adoc, která je vždy umístěna přímo v kořeni složky návodu.
Pokud návod vyžaduje stránku s často kladenými dotazy (FAQ), obsah je psaný do samostatného souboru faq.adoc.
Pokud se návod skládá z více tematicky různých částí, každé téma má vlastní podsložku pojmenovanou podle tématu.
Obrázky a další soubory se ukládají do složky /media uvnitř složky daného návodu.
Pokud se stejný obrázek používá na více místech, je vytvořený symbolický link na původní obrázek se stejným jménem

Ukázka 1. Ukázka struktury repozitáře

help.fit.cvut.cz
├── cs/
│   └── courses/
│       ├── index.adoc
│       ├── faq.adoc
│       ├── content/
│       │   ├── index.adoc
│       │   ├── news.adoc
│       │   └── media/
│       │       ├── icon.png
│       │       └── diagram-cs.png
│       ├── processes/
│       │   └── index.adoc
│       └── media/
│           └── logo.png
│
├── en/
│   └── courses/
│       ├── index.adoc
│       ├── faq.adoc
│       ├── content/
│       │   ├── index.adoc
│       │   ├── news.adoc
│       │   └── media/
│       │       ├── icon.png
│       │       └── diagram-en.png
│       ├── processes/
│       │   └── index.adoc
│       └── media/
│           └── logo.png
│
├── .attributes.adoc
└── .shared-content.adoc

Pojmenovávání

Obecná pravidla pro pojmenování souborů a složek jsou:

Anglické pojmenování
Malými písmeny
Bez mezer
Slova oddělovat spojovníkem (klávesa -)
Anglické i české verze návodů mají tentýž název

Pojmenování návodů:

Úvodní stránka se vždy jmenuje index.adoc.
Ostatní stránky se pojmenovávají tak, aby název co nejlépe odpovídal obsahu stránky
Stránka s často kladenými otázkami (FAQ)

Pojmenování obrázků a jiných médií:

Název by měl popisovat obsah média
Média s českým obsahem končí na -cs, např. courses-architecture-fitpages-cs.png nebo courses-architecture-fitpages-cs.drawio a jsou umístěna u české verze návodu
Média s anglickým obsahem končí na -en, např. courses-architecture-fitpages-en.png nebo courses-architecture-fitpages-en.drawio a jsou umístěna u anglické verze návodu
Pokud se jedná o médium bez jazykového obsahu, je koncovka vypuštěna, např. redundant.png
Pokud neexistuje dvojjazyčná varianta, je vytvořen symbolický link na existující médium se stejným[1] názvem jako existující médium
Série obrázků se čísluje od jedničky a bez úvodní nuly, např. image-1-cs.png nebo image-9-cs.png

Média

Pravidla pro pracování s médii jsou následující:

Média jsou ukládány podle konvencí struktury médií
Média jsou pojmenované podle konvencí pojmenovávání médií
Preferovány jsou obrázky v bílém režimu s českou lokalizací pro české návody a s anglickou pro anglické návody
Preferováný formát obrázků je PNG
Je preferováno fotit celé okno obrazovky
Jako ukázkového uživatele se využívá fiktivní osoba Kevin Flynn (flynnkev@cvut.cz)
Pro případ nutnosti uvedení QR kódu lze využít následující:

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í.[2] Doporučená šířka je 1 200 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.

Kód pro kompresi s využitím ImageMagick

Windows / Linux

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>

MacOS

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

Pravidla pro psaní AsciiDoc souborů:

Definice atributů, makra include::, :toc:, :imagesdir: apod. se píší na začátek souboru
Každá stránka musí mít právě jeden titulek – nadpis první úrovně [3]
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í
- 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
Před nadpisem se píší dva prázdné řádky, za nadpisem jeden prázdný řádek

Každá věta se píše na samostatný řádek[4]

Pokud se u seznamů jedná o dodatek k hlavní větě, může být dodatek na stejném řádku, pokud je relativně krátký:

* Toto je hlavní věta, která může být delší. Toto je kratší dodatek.
* Toto je další hlavní věta, která je dlouhá.
  Toto je delší dotatek, vysvětlujícíc hlavní větu.
* Toto je další věta.

Pokud je bod rozdělený na více řádků, je věta odsazena na stejnou úroveň jako první věta stejné úrovně:
```
* První věta.
  Druhá věta.
** Třetí věta.
   Čtvrtá věta.
* Pátá věta.
```

Body seznamu se píší bez prázdných řádků mezi jednotlivými body
Pokud je bod seznamu:
- pokyn, který uživatel musí provést, píšeme na konci věty tečku (v případě, že následuje obrázek, lze použít i dvojtečku)
- pouze bod oznamující nějakou skutečnost, tečku nepíšeme
Každý soubor končí prázdným řádkem
Pro vkládání obrázků používá atribut :imagesdir:
Pomlčky (nikoli spojovníky) se píší pomocí -- (vykreslí se jako –) nebo přímo Unicode znakem –.
Odkazy:
- by měly obsahovat název, kam odkazují
- na sekci stejného návodu se dělají pomocí makra xref:, např. xref:conventions[Konvence]
- na jiné návody se dělají pomocí makra xref:, např. xref:./rooms/index.adoc#labels[Značení]
- na webové stránky nepoužívají makro link:, např. https://example.com[Example]
- na webové stránky, kde odkaz je uvnitř atributu, používají pro čitelnost makro link:, např. link:{example-site-url}[Example]
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/)
Je dobré využívat makra:
- btn:[], vykreleno jako Tlačítko
- menu:[], vykreleno jako Soubor › Uložit › Uložit jako
- kbd:[], vykresleno jako Ctrl+S
V případě využívání maker 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 popsanou v Courses FAQ
Pro zamezení formátování, např. v blocích kódu, se používá jednoduché +, trojité +++ nebo makro pass:[]. Použít se dá i zpětné lomítko \, ale pouze v případě, že je kód dostatečně čitelný
Snažte se vyvarovat větám jako … naleznete zde nebo … viz. tato stránka

Proměnné a sdílený obsah

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.

Veškeré proměnné jsou definovány v souboru .attributes.adoc uložený v kořeni souborové struktury a pro použití musí být zahrnuty do souboru pomocí makra include::./attributes.adoc[]. Editor tak dokáže validovat, zda proměnná existuje nebo zda se vůbec používá. Jejich využití je silně preferováno pro výrazy využívané napříč návody.[5]

Proměnné avšak neumožňují práci s víceřádkovým obsahem. Pro tento účel je doporučeno využívat soubor .shared-content.adoc definovaný globálně taktéž v kořeni souborové struktury. Práce s víceřádkovým obsahem je následující:

.shared-content.adoc

Do souboru napíšete obsah, který chcete sdílet napříč soubory a obalíte ho tagem:

// tag::outlook-recommendation[]
Pro plnou kompatibilitu doporučujeme využívat aplikaci *Microsoft Outlook*.
// end::outlook-recommendation[]

Využití v návodu

V návodu pak stačí v makru include:: tag napsat:

include::../.shared-content.adoc[tag=outlook-recommendation]

Ustálené výrazy

Z důvodu zachování konzistence napříč návody a dodržování konceptu DRY, 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ší.

Časté výrazy

Tato doporučení definují preferované formulace a zápis často používaných výrazů:

Přihlaste se uživatelským jménem a heslem ČVUT.
- Je doporučeno přidat odkaz, ukázka: Přihlaste se uživatelským jménem a heslem ČVUT.
- Vyvarovat se používání username, pokud je to možné.
… 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.[6]

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).

Git

Pravidla pro práci s verzovacím systémem Git:

Jako prefix přidejte návod, kterého se změna týká. Např. projectsfit: Fix typo
- Pokud provádíte změny ve více návodech najednou nebo se změna týká celého projektu, použijte prefix meta
Titulek commit zprávy pište v imperativu s počátečním velkým písmenem, bez tečky na konci a pokud možno do 69 znaků (max 80 znaků), např. meta: Add README, ne meta: Added README
- Na konec zprávy lze přidat odkaz na issue ve tvaru #ID, kde ID je číslo issue, které commit řeší. Např. print: Add new printer (#123)
U pojmenování větví se doporučuje používat prefix s číslem issue, které větev řeší. Např. 123-fix-link
Nastavte si git user.name . Návod najdete např. v dokumentaci GitHub Docs
V nejvyšší možné míře využívejte merge requesty.
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

Ostatní

Ostatní pravidla, která se nehodila do dřívějších kategorií, jsou:

Pokud koliduje admonition blok s toc, využijte návod pro práci s kolizemi
Pro zveličení významu slova nebo věty může autor využít tučné písmo nebo kurzívu
Na FAQ vždy používat samostatný soubor s titulkem Často kladené otázky a názvem faq.adoc, využívejte makro qanda.
Je doporučené, aby návody měly sekci Podpora, ve které budou uvedeny kontakty na koho se obracet v případě potíží nebo nápadů na zlepšení.[7]``

Pokud by se v budoucnu objevila dvojjazyčná verze, je jednodušší zkontrolovat koncovku média a jazykovou složku, ve které se médium nachází a poté médium vyměnit. ↩
V opačném případě může mít jedna stránky velikost v několika MB. ↩
= Title v AsciiDocu. ↩
Hlavně nezalamovat text na fixní počet znaků! ↩
Typicky pro odkazy. ↩
Poslední čtyřčíslí je telefonní číslo v rámci interní sítě. ↩
Ne vždy se jedná nutně o oddělení ICT. ↩