konvence

Konvence

K dobré Wiki nestačí jen hromada článků, které pokrývají vše potřebné, ale je také nutné, aby tyto články měly nějakou úroveň. Tím není myšlena jen obsahová (ta je samozřejmě stále primární), ale také často opomíjená úroveň grafická a stylistická.

Časem se na naší Wiki vyvinuly jisté konvence - ustálené zvyklosti v tom, jak by měl správný článek vypadat, jak by měly být jednotlivé části formátovány a jak by měly vypadat určité postupy.

Pokud se vy, autoři, budete těmito konvencemi řídit, ušetříte tím práci nejen nám administrátorům, ale hlavně uživatelům Ubuntu, kteří budou mít k dispozici kvalitní, přehledné a - co je asi nejdůležitější - stejné návody.

Konvence rozhodně nejsou žádná dogmata - budeme jen rádi, pokud navrhnete změnu, která povede ke zlepšení Wiki.

Typografie

Příkazy, adresáře, balíky

Názvy adresářů, souborů, balíků nebo příkazy jsou v souvislém textu sázeny strojopisným písmem.

Delší příkazy (mimo text), výpisy příkazů, obsahy souborů, apt řádky repozitářů a další jsou sázeny do speciálního rámečku.

Pro zdrojové kódy některých programovacích nebo skriptovacích jazyků (C++, Bash, Python…) jsou k dispozici speciální rámečky zvýrazňující syntaxi atp.

Pokud potřebujete navigovat uživatele nabídkou, používejte tučné písmo a šipky: Aplikace → Příslušenství → Terminál. Používejte opravdu šipky (které získáte klávesovou zkratkou Alt+I) nikoli pomlčku a ostrou závorku ->.

Tučným písmem sázejte také názvy „tlačítek“, karet (záložek) a dalších prvků v okně aplikace, názvy aplikací a nástrojů atd.

Klávesy a zkratky

Klávesové zkratky můžete sázet pomocí značek <key></key>. Písmena pište malá, velká jsou vyhrazena pro „zkratky“ různých dalších tlačítek - například C slouží pro Ctrl (všechny možnosti jsou ukázány níže). Posloupnosti se píší s pomlčkou <key>C-c</key> vytvoří Ctrl+C.

  • <key>C</key> - Ctrl
  • <key>A</key> - Alt
  • <key>S</key> - Shift
  • <key>E</key> - E
  • <key>Tab</key> - Tab
  • <key>Left</key> -
  • <key>Right</key> -
  • <key>Up</key> -
  • <key>Down</key> -

Vytvořit můžete samozřejmě „klávesu“ s jakýmkoli textem: <key>F10</key> - F10, <key>Home</key> - Home atp.

Struktura návodů

Návody se od sebe mohou velmi lišit podle toho, k čemu jsou určeny, ale vždy je nutné dodržet určitou základní strukturu.

Zcela jasnou (a vždy stejnou) strukturu mají návody týkající se popisu nějaké aplikace. Příklad s komentáři naleznete na Aplikace.

Na úplně první řádek návodu patří varování nebo chcete-li upozornění uživatele na některé závažné skutečnosti.

Jednotlivé „hlavičky“ naleznete na stránce Hlavička.

Každý návod musí nějak začít a podle svého začátku je často hodnocen celý. Na úplný začátek je vhodný krátký úvod (stačí i jeden odstavec o dvou třech větách), který začíná ikonou (pokud se jedná o program, tak jeho ikonou, u jiných návodů vhodnou ikonou ze seznamu), a v němž se uživatel dozví o čem návod je a komu je určen (u programů se hodí i stručný popis jeho využití).

Po úvodu je potřeba uvést některé další, méně „závažné“ informace:

Terminál

Návod popisuje nastavení přes grafický nástroj, ale má i variantu pro ruční nastavení přes terminál.

Pokud potřebujete nastavit/upravit/udělat XYZ ručně (tzn. v textovém prostředí), čtěte Příkazová řádka.

{{:terminal.png}} Pokud potřebujete nastavit/upravit/udělat XYZ ručně (tzn. v textovém prostředí), čtěte [[Příkazová řádka]]

Zde jsou možné i jiné možnosti zápisu. Příklad ze stránky Získání snímku obrazovky. U kratších návodů není třeba vytvářet zvláštní stránku, ale je možné dát informace přímo jako samostatnou kapitolu. Příkladem může být návod Automatické bezpečnostní aktualizace.

Časová náročnost

Postup je časově náročný a neumožňuje přerušení za běhu. Typicky přechod na novější vydání, který (bez poškození systému) není možné za běhu přerušit.

Celý postup je velmi časově náročný a neumožňuje jednoduché přerušení za běhu.

{{page>Konvence/Čas}}

Lokalizace

Je potřeba znalost anglického jazyka.

XYZ není lokalizován do českého jazyka, budete tedy potřebovat alespoň základní znalost angličtiny.

{{:locale.png}} XYZ není lokalizován do českého jazyka, budete tedy potřebovat alespoň základní znalost angličtiny.

Ostatní

Alternativně k uvedenému je potřeba zmínit odlišnosti:

  • Funguje jen pro Ubuntu, v jiných prostředích nefunguje nebo je potřeba nebo změnit.
  • Návod popisuje postup jen přes terminál/grafické prostředí, přičemž druhá možnost existuje, ale není popsána.
  • Návod funguje (je potřeba) až od/do verze.

Před začátkem samotného návodu je potřeba uvést věci, které uživatel musí nebo by měl udělat, než začne. Patří sem:

  • Instalace potřebného softwaru
  • Případná záloha dat a/nebo konfiguračních souborů
  • Vypnutí/zapnutí některých aplikací nebo nástrojů

Po skončení návodu je dobré uvést:

  • Známé problémy a způsob jejich řešení
  • Tipy a triky na zlepšení funkcí nebo zrychlení programu

Na úplný konec článku patří (externí) odkazy:

  • Domovská stránka projektu/programu
  • Originál návodu (je-li překladem)
  • Návod na anglické Wiki
  • Články na českých linuxových serverech (AbcLinuxu, LinuxEXPRES, Root…) se stejnou tematikou
  • Témata na českém Ubuntu fóru doplňující/rozšiřující návod

Používání a tvorba obrázků

Obrázek často řekne víc jak tisíc slov, a proto je vhodné je používat často, ale s rozmyslem.

Obrázky je nejlepší použít v úvodu návodu, kde slouží jako ukázka vzhledu aplikace nebo nástroje. V samotném návodě slouží k doplnění textu názornou ukázkou nebo k předvedení funkce nebo správného nastavení.

Pro podrobnější informace navštivte stránku Obrázky.

Používání ikon

Celý návod můžete velmi zpřehlednit a graficky vylepšit použitím ikon.

Specifické situace

Pro různé „specifické“ části návodů je vhodné používat i přímo stejné věty, ikony a úpravu.

Příklady specifických situací naleznete na stránce Specifické situace.

Čeho se vyvarovat

Terminál

Pokud to není nutné, vyhněte se používání terminálu (výjimku mohou tvořit návody označené jako pro pokročilé uživatele).

Špatně: Použijte příkaz sudo apt-get install nazevbaliku.

Správně: Nainstalujte balík nazevbaliku

Nepoužívejte dnes již zastaralý navigační pruh.

Duplikace návodů

Váš návod k zajímavé aplikaci opravdu nemusí obsahovat deseti řádkový odstavec o instalaci softwaru ze zdrojů ani úvod do práce v terminálu.

Drobnosti

  • K odkazům na anglicky psané stránky přidejte vlaječku -
  • V textu uvádějte co nejvíce (relevantních) odkazů do Wiki.

Gramatika a stylistika

  • Pište spisovnou češtinou (slovenštinou) a používejte kontrolu pravopisu!
  • Pamatujte, že nepíšete dopis - nepište tedy „věci“ jako Vám, Vás atd.
  • Čtenáři vykejte - používejte tedy druhou osobu množného čísla - udělejte, otevřete, zkopírujete. Rozhodně netykejte, ani nepoužívejte první osobu množného čísla.
  • Rozhodně se vyhněte rádoby vtipným výrazům jako „widle“, „M$“ atd.

Příklady dobře napsaných návodů

  • Poslední úprava: 2019/02/25 18:21
  • autor: 127.0.0.1