[[wiki:jakpsat]] Forum
Wiki
 

Jak psát dokumentaci

Tento dokument se snaží být příručkou o tom, jak psát dokumentaci tak, aby se zde netlouklo tisíc různých stylů. Jednoduše si tahle stránka klade za úkol určit styl, způsob strukturování apod.

Jazyk

Piš pokud možno spisovně. Zvykni si tykat, tobě taky tykám. Je povoleno psát česky a slovensky, ale běda jiným jazykům.

Diakritika

Psaní diakritických znamének je velice důležité, ačkoliv tě může zdržovat. Slova bez háčků a čárek mohou totiž na první pohled mít úplně jiný význam, viz např.:

pracka, dopisu, kocka, micky, macky, vacky

Oproti:

pračka, dopíšu, kočka, míčky, mačky, váčky nebo vačky

Úrovně nadpisů

V dokumentu bude vždy jeden hlavní nadpis,

====== Hlavní nadpis ======

a ostatní budou nižší úrovně. Úrovně nepřeskakujeme a nepíšeme je všemi písmeny velkými – jsme slušní lidé a neřveme na sebe ;-). Ukázka nesprávných úrovní:

=== HLAVNI NADPIS ===
= JAK ZEBRAK DO JESTE VETSI NOUZE PRISEL =
= KASPARKUV HROBECEK =

Správně by to mělo být takto:

====== Hlavní nadpis ======
===== Jak žebrák do ještě větší nouze přišel =====
===== Kašpárkův hrobeček =====

Interpunkce

Kde se píšou mezery

Mezeru píšeme pouze za interpunkčním znaménkem. Nesnažte se tedy psát

Ahoj ,světe !

Zakončení vět

Vždy pouze jedním interpunkčním znaménkem, případně smajlíkem.

Čárky ve větách

Hlavně před slovy který, kterým začíná vedlejší věta přívlastková. Častou chybou je také nezakončení vložené věty čárkou, viz příklad:

Anička, která zpívala v SuperStar se stala hvězdou.

Správně to má být:

Anička, která zpívala v SuperStar, se stala hvězdou.

Závorky

Mezery píšeme vně závorek s výjimkou interpunkce, ta se píše hned za koncovou závorku, nikoliv třeba takto:

Kouknul jsem na něj( no pohled to byl hrozný) .

Správně se to napíše:

Kouknul jsem na něj (no, pohled to byl hrozný).

Pokud je celá věta v závorkách, začíná pochopitelně velkým písmenem a i tečka je uvnitř (bez nároku na mezeru za tečkou), např.

(Tak tohle jsem asi vážně dělat neměl.)

Závorky nevnořuj, pokud chceš něco vnořit, použij místo dalších závorek oddělení pomlčkami.

Pomlčky

Pomlčky jsou hodně kritickou záležitostí. Odvykni si pomlčku psát jedním mínusem, takto:

-

ale piš ji dvěma mínusy za sebou – takto:

--

Rozdíl je totiž velký. Jeden mínus vytváří takzvaný spojovník, který uplatníš ve složených výrazech a ve vazbě sloveso-li. Teprve dva mínusy vytvářejí opravdovou pomlčku.

Odstavce a seznamy

Dodržuj, k čemu je odstavec a seznam určen. Místo nového řádku (pomocí \\) začni rovnou nový odstavec. Pokud píšeš seznam, zamysli se nad tím, zda použít odrážkovaný či číslovaný – vzhledem k povaze ŽVAVu se bude nejčastěji objevovat odrážkovaný. Co se týče teček na konci položek seznamu, záleží na tom, zda je položka větou, či nikoliv. Pokud položka seznamu dokončuje větu z předešlého odstavce, začíná vždy malým písmenem a končí čárkou, pouze poslední položka končí tečkou. Ve všech ostatních případech položka seznamu začíná vždy velkým písmenem!

Zvýrazňování

Nikdy nezvýrazňujeme podtrženým písmem a nikdy nezvýrazňujeme velkým písmem. Tučným písmem klademe důraz na nějakou část textu, čehož využívej s citem. Kurzívou potom zvýrazňuj konkrétní názvy tlačítek, odkazů a podobných záležitostí – nesnaž se to cpát do uvozovek apod.

Důležité pravidlo: interpunkce za zvýrazněným slovem musí být také zvýrazněna!

Vzorce

Vzorce píšeme dovnitř “HTML tagů” code, případně odsazené dvěma mezerami z kraje řádku, takže vytvoří

takovýto rámeček.

Pro násobení používáme symbol *, mocniny vyjadřujeme jako ^exponent, nikoliv pomocí “HTML tagu” sup, protože ten uvnitř code nefunguje.

 
wiki/jakpsat.txt · Poslední úprava: 27/11/2005 14:29 autor: ViR
 
Recent changes RSS feed Driven by DokuWiki