Psaní dokumentace
Bude skvělé, pokud se zapojíte do tvorby nebo překládání dokumentace. Jak na to?
Pro editace dokumentace musíte mít oprávnění, o které si požádejte zde na fóru. Pokud si nebudete čímkoliv jisti, napište na do sekce Dokumentace.
Jak psát?
Dokumentace je určena především lidem, kteří se s tématem teprve
seznamují. Buďte si toho vědomi po celou dobu psaní. Text musí být
koncipován tak, aby vedl čtenáře od jednoduchého ke složitému. V úvodu
není potřeba říci o tématu všechny podrobnosti (a už vůbec ne pomocí
agresivních .[note] poznámek), čtenáře nechceme zahltit.
Cení se stručnost. Cokoliv napíšete, zkraťte na polovinu. Až se vám to podaří, pak to zkraťte opět na polovinu.
Cení se schopnost věc vysvětlit. Než začnete psát, pokuste se téma vysvětlit svému kolegovi (nebo psovi) a pak se teprve pusťte do tvorby.
- Naučte se syntax, kterou si můžete vyzkoušet na pískovišti, kde nemůžete způsobit žádnou škodu
- Dodržujte Coding Standard
- Názvy proměnných, tříd a metod pište anglicky
- Všechno pište pro verzi Nette Framework 2.0 a PHP 5.3 (s výjimkou dokumentace pro 0.9)
- O odlišnostech verzí 5.2 a 5.3 v samotném frameworku (namespace se
nepočítají) píšeme jako varování (
.[warning]) - Názvy tříd včetně jmenných prostorů uvádějte při první zmínce, pak už bez namespace
- Šetřete zvýrazňovači všeho druhu, od tučného písma po
rámečky
.[note] - V textu dokumentace spíše „mykáme“ a jsme zdvořilí
- Perex je stručnou upoutávkou k tématu, nepleťte si ho s prvním odstavcem
- Kód se snažte formátovat tak, aby se nezobrazovaly posuvníky
- Zdrojová podoba stránky by měla být přehledná, nešetřete volnými řádky mezi odstavci, titulky, kódem apod.
- Když jste hotovi, zavítejte na Stav překladu dokumentace a
případně změňte stav
PřeloženýnaPřeložený - neaktuální.
Jak vytvořit překlad?
Úvodní stránka anglické dokumentace je připravená, je třeba doplnit obsah. Ten se v tuto chvíli zobrazuje přeložený přes Google Translator, tak se tím nenechte zmást. Asi nejjednodušší způsobem je zkopírovat zdrojový kód české stránky a použít jej jako základ stránky anglické. Zdrojový kód si můžete nechat před-přeložit Google Translatorem, jen je potom potřeba upravit změny, které udělá ve wiki syntaxi.
Překlad by měl používat jednoduchou slovní zásobu, protože je určen nejen pro rodilé mluvčí, ale pro kohokoliv.
Než se pustíte do díla, zapište se na Stavu překladu dokumentace, ať se s někým omylem nepřekrýváte nebo ať zbytečně nepřekládáte, co ještě nemá finální podobu.