Dokumentace/Průvodce stylem
Přehled
Tento průvodce stylem poskytuje návod pro psaní a úpravy technické dokumentace v MediaWiki a dalších technických oblastech. Poskytuje tipy, které vám pomohou napsat jasnou a stručnou technickou dokumentaci v jednoduchém jazyce. Odkazuje také na další zdroje o technickém psaní a úpravách obecně.
Dobrá technická dokumentace usnadňuje lidem přispívat do projektů Wikimedia. Je důležité dodržovat jasné standardy a stylové pokyny pro psaní a úpravy dokumentace, zvláště když přispěvatelé a čtenáři mají různé úrovně dovedností a zkušeností. Ať už se považujete za spisovatele nebo ne, vaše příspěvky jsou potřebné a ceněné!
Příručka stylu na anglické Wikipedii
Příručka stylu na anglické Wikipedii podrobně pokrývá obecná témata psaní (jako je interpunkce) a shrnuje klíčové body jiných stylových příruček. Může to být užitečná reference pro každého, kdo píše nebo upravuje technickou dokumentaci v angličtině napříč projekty Wikimedia, zvláště pokud místní wiki nemá konkrétnější pokyny.
Tato stránka obsahuje základní pokyny a tipy, které vám pomohou začít s technickou dokumentací. Obsahuje některé informace specifické pro technickou dokumentaci, která není zahrnuta ve Wikipedii Manual of Style.
Publikum a obsah
Psaní pro technické publikum
Než začnete psát, zvažte publikum vaší práce:
- Kdo bude číst tuto technickou dokumentaci?
- Odkud pochází?
- Jak dobře jsou obeznámeni s pojmy, které prezentujete?
- Co mohou potřebovat vědět, aby porozuměli?
Jakmile porozumíte svému publiku, budete mít lepší smysl pro to, co potřebujete ke komunikaci.
- Pokud víte, že vaše publikum je vysoce technické a zná procesy, které popisujete, pak nepotřebujete vysvětlovat základní pojmy.
- Pokud víte, že se vaše publikum učí nebo nezná procesy, které popisujete, zahrňte vysvětlení základních pojmů a odkazy na další informace.
Psaní s určitým účelem
K čemu bude sloužit vaše technická dokumentace? Existuje mnoho důvodů, proč psát dokumentaci. Je užitečné vědět, proč píšete a jaký je váš cíl, než začnete.
- Je to naučit někoho, jako nováčka, o procesu nebo konceptu?
- Je to ukázat někomu, jak sledovat proces?
- Má to poskytnout pozadí a kontext pro koncept nebo proces?
- Je to odkaz určený k poskytování informací?
Psaní v kontextu
Když se rozhodujete, co napsat a jak to čtenáři zarámovat, může vám pomoci definovat kontext nebo příležitost pro vaše psaní. Vaše komunikace probíhá v kontextu větší situace. Kontext může být ohraničen dobou, ve které píšete, typem dostupné technologie, vaší geografickou polohou a kulturou nebo současnou kulturou a komunikačním stylem vašich čtenářů. Tato příležitost může být osobní a může vycházet ze situace, která vás motivovala k vytvoření nebo vylepšení části dokumentace.
Pokud například píšete technickou dokumentaci pro projekty Wikimedia, zvažte kulturu vytvořenou jednotlivci, kteří se těchto projektů účastní. Jak byste mohli nejlépe umístit své psaní do kontextu této komunity a její kultury, abyste vytvořili co nejsmysluplnější a nejužitečnější technickou dokumentaci?
Uživatelské testování a zpětná vazba
Vytvářejte technickou dokumentaci ke sdělení nápadů a konceptů skutečnému uživatelskému publiku. Přirozeně by toto publikum mělo hrát klíčovou roli v tom, jak je dokumentace utvářena a přetvářena. Přemýšlejte o tom, jak můžete získat informace o zkušenostech vašich uživatelů. Udělejte si čas na zodpovězení následujících otázek:
- Obsahuje vaše dokumentace mechanismus pro zpětnou vazbu?
- Dokážete se včas zapojit do rozhovorů s publikem, abyste dosáhli zlepšení?
- Můžete použít fóra jako Stack Overflow nebo mailing listy ke kontrole, zda váš dokument odpovídá na nejčastější otázky, které lidé mají ohledně vašeho konkrétního tématu?
Jasnost a konzistence
Přehlednost a konzistence usnadňuje přístup, čtení a vytváření technické dokumentace napříč projekty MediaWiki/Wikimedia. Technická dokumentace je napsána pro široké publikum a upravována řadou přispěvatelů.
Hlas, tón, použití gramatiky, styl a formát by měly být konzistentní napříč technickou dokumentací a podobnými kolekcemi obsahu. To pomáhá čtenářům naučit se orientovat v informacích a přispěvatelům usnadňuje pochopení, jak upravovat a přidávat nové informace.
Rozhodování o typu dokumentu
Nejprve určete své hlavní publikum, účel a kontext, abyste se rozhodli, jaký typ dokumentu vytvoříte.
| Příklad publika | Účel[1] | Potenciální typy dokumentů | Příklad |
|---|---|---|---|
| Nováček se zájmem naučit se, jak se stát uživatelem Toolforge | Učit se | Cvičení, často kladené otázky, průvodce Začínáme | Cloudové VPS a Toolforge FAQ |
| Zkušený technický přispěvatel se snaží vyřešit známý problém | Dosažení cíle | Návod, jak na to | Můj první nástroj OAuth Flask |
| Jednotlivec snažící se pochopit historii ORES a jak se vyvíjel | Rozumět | Vysvětlující článek, příspěvek na blogu, "přehled" | Služba umělé inteligence "ORES" poskytuje wikipedistům rentgenové specifikace, aby viděli špatné úpravy |
| Člověk, který hledá definici SSH klíčů | Informovat se | Referenční příručka, glosář | Slovníček |
Jazyk
Tato část stručně zmiňuje některá témata, která stojí za to prozkoumat jinde podrobněji.
Vždy zkontrolujte svá slova a výrazy podle těchto kritérií na Wikt:
Wikislovníky pokrývají stovky jazyků, explicitně uvádějí gramatické a lexikální rysy slov a jejich skloňování, poskytují podrobné kontextové popisky (včetně žargonu, britské vs. americké angličtiny) a odhalují, jak jsou přeložitelné termíny ve stovkách dalších jazyků.
Obyčejná angličtina
Pamatujte prosím: Mnoho návštěvníků těchto stránek není rodilými mluvčími angličtiny.
Pro dokumentaci psanou v angličtině nejlépe funguje Plain English (také nazývaná plain language). Prosté písmo je nejsrozumitelnější pro různé publikum a také se nejsnáze překládá. Existuje řada dobrých nástrojů pro kontrolu vašeho psaní v pokynech pro psaní Tech News na Meta-Wiki.
- Vyhněte se dvojznačnosti, žargonu a vágním nebo složitým formulacím.
- Používejte slova, kterým bude vaše publikum rozumět, a dostatek slov k předání vašeho sdělení.
- Definujte pojmy, které nemusí být zřejmé jednotlivcům, kteří jsou noví v předmětu, o kterém píšete.
- Udržujte odstavce a věty krátké a výstižné.
- Kontrakce používejte nebo ne. Jsou konzistentní.
Hlas a tón
MediaWiki je místo, kde může kdokoli upravovat. Proto může být obtížné udržet konzistentní hlas a tón v dokumentaci.
Zvažte použití těchto prvků při psaní:
| Hlas a tón | Co to znamená | Místo toho | Zkuste to |
|---|---|---|---|
| Přátelský | Technická dokumentace nemusí znít akademicky nebo suchopárně. Pište svým posluchačům, jako by tam byli osobně. | Než začnete, uživatel si musí vytvořit účet. | Začněte vytvořením účtu. |
| Profesionální | Technická dokumentace může být přátelská, ale měla by zůstat profesionální. Použijte Inkluzivní jazyk. | Nedělejte hromadu změn. | Pokuste se provést minimální změny. |
| Pozitivní | Vyhněte se používání záporných větných konstrukcí. Vysvětlete věci z hlediska toho, co dělat. Je těžší mentálně rozebrat složitou negativní větu! | N se nestane, pokud to neuděláte XYZ. | Chcete-li provést N, udělejte XYZ. |
| Aktivní | Zkuste použít aktivní hlas, kromě případů, kdy diplomacie vyžaduje pasivní hlas. | Rozšíření musí být zaregistrováno. | Rozšíření musíte zaregistrovat. |
| Bez pohlaví | Přijměte genderově inkluzivní jazyk. Předpokládejme, že vaše publikum zahrnuje všechny genderové identity. | Když klikne na Uložit | Když uživatel klikne na Uložit |
| Zahrnující | Používejte alternativy k běžným slovům nebo frázím, které mohou neúmyslně posílit nevhodné stereotypy. | Toto uživatelské rozhraní je šílené. | Toto uživatelské rozhraní by se dalo vylepšit. |
| Bez frustrace | Vyhněte se výrazům jako "snadné" a "jednoduché", které mohou být pro méně technicky zdatné uživatele frustrující. | Jednoduše si vytvořte uživatelský účet. | Vytvořte si uživatelský účet. |
| Bez hovorových výrazů | Může být matoucí používat hovorové výrazy, vtipy, slovní hříčky nebo změny frází, kterým nerodilí mluvčí angličtiny nebo jednotlivci z jiných regionů nemusí snadno rozumět. | Vytvoření uživatelského účtu je hračka. | Vytvoření uživatelského účtu vyžaduje dva kroky. |
Úhel pohledu
- Když oslovujete své publikum, použijte druhou osobu ("vy" nebo předpokládané "vy").
- Vyhněte se first person ("já" nebo "my"), pokud nepíšete FAQ s otázkami položenými z pohledu první osoby.
- Pro většinu dokumentace zaměřené na cíle nebo proces použijte imperativní náladu.
Datumy
- Vždy používejte celý čtyřmístný rok.
- Použijte absolutní data ("v květnu 2037") namísto relativních dat ("příští rok v květnu").
- Vyhněte se přidávání dat, která budou vyžadovat pravidelné ruční aktualizace. Příklad: Když odkazujete na aktuální rok, napište
{{#time: Y }}místo 2024, bez ohledu na to, jaký je právě rok.
Strukturování stránek
Přehled
Všechny stránky by měly obsahovat sekci s přehledem (také nazývanou Lead section), která vysvětluje:
- Účel stránky
- Publikum stránky
- Předpoklady, které musí čtenář znát, než bude pokračovat (např. pracovní znalost Pythonu)
- Software nebo nástroje, které bude čtenář potřebovat k dokončení procesů nebo úkolů uvedených na stránce (např. nainstalovaná Java)
- Případ použití, případová studie, praktické pochopení produktu, služby nebo nástroje v akci. (volitelný)
Obsah
- Každá stránka by měla obsahovat obsah, aby byly informace snadno přístupné.
Titulky a nadpisy
- Použijte zásady pro nadpisy.
- Udržujte písma nadpisů konzistentní v celé dokumentaci.
- Volitelné použití kotvy k propojení sekcí nebo podsekcí na stejné stránce.
- Za nadpisy oddílů přidejte prázdný řádek. To má vliv na jak je obsah zabalen pro překlad.
- Neumisťujte nadpis před svůj přehled nebo hlavní sekci.
Informační tok
Stránky technické dokumentace by měly mít konzistentní vzor napříč kolekcemi obsahu.
Ideální vzor pro každou stránku může být:
- Název stránky
- Úvod/Přehled
- Nadpis
- Obsah
- V případě potřeby podnadpis
- Obsah
- V případě potřeby podnadpis
- Obsah
Formátování textu
Příklady formátování kódu a další technické prvky
Formátování odlišuje kód a další technické prvky od běžného textu.
| Účel | Wiki-značky | Výsledek | Okolnosti |
|---|---|---|---|
| Code | <code>code</code>
|
code
|
Použijte pro krátké řetězce kódu, včetně označení wikitextu.
V rámci |
| Syntax highlight |
<syntaxhighlight lang="css">
.citation {
margin: 0;
}
</syntaxhighlight>
Text před |
.citation {
margin: 0;
}
Předcházející text |
Pomocí tagu <syntaxhighlight lang="...">...</syntaxhighlight> zdokumentujte několik řádků kódu a zachovejte mezery a zalomení řádků. Atribut inline umožňuje jeho použití v rámci existujícího odstavce.
Všimněte si, že uprostřed bloku Další podrobnosti najdete na stránce Rozšíření:SyntaxHighlight. |
| Preformatted | <pre>preformatted text
|
preformatted text
with indent
|
Stejné jako výše (zachovat mezery a zalomení řádků), ale bez zabarvení. |
| Keyboard input | <kbd>keyboard 123</kbd> (vs keyboard 123)
|
keyboard 123 (vs keyboard 123) | Pro skutečný vstup z klávesnice použijte <kbd>...</kbd> – text, který uživatel zadá do vstupního pole nebo na příkazový řádek terminálu. Zobrazuje se v prostém monoprostoru.
|
| Variables | <var>variable</var>
''italics''
|
variable
italics |
Pro proměnné jako název-klíče-zprávy a ukázkové názvy jako Název mé stránky použijte kurzívu.
Nepoužívejte interpunkci, jako je <YOURPASSWORD>, protože čtenáři nevědí, že lomené závorky jsou šum a zadají je. |
| Bold | '''bold'''
|
bold | Obecně se používá pouze pro první výskyt názvu stránky a pro vzácné zdůraznění klíčových slov, aby se umožnilo snadnější procházení seznamů nebo odstavců.
Někdy tučné je nadměrně používáno pro zdůraznění. Místo toho můžete zvážit použití šablony, např. {{Caution}}, {{Note}} nebo {{Warning/core}}.
|
| Quotations | "quotation marks"
Předcházející text
Následující text |
"quotation marks"
Text beforeText after |
Pro krátké části obsahu citované z jiných zdrojů používejte uvozovky.
Pro delší části obsahu použijte blockquote. |
| Abbreviations | JavaScript (JS)
|
JavaScript (JS)
JS |
Zkratky byste měli definovat při prvním použití. Použijte buď prostý text a závorky, nebo HTML značku abbr. |
| Keypress | {{Key press}}
|
Ctrl+⇧ Shift+I | Zobrazují se konkrétní stisky nebo kombinace klávesnice. Rozsáhlé příklady na VisualEditor/Portál/Klávesové zkratky.
Poznámka: Tato šablona nemusí existovat na jiných wikinách. |
| Button | {{Button}}
|
Ukázat náhled | Zobrazují se tlačítka uživatelského rozhraní, na která je třeba kliknout.
Poznámka: Tato šablona nemusí existovat na jiných wikinách. |
Odkazy
| Typ | Účel | Jak implementovat | Příklad |
|---|---|---|---|
| Místní | Odkaz na jiné stránky MediaWiki |
|
MediaWiki |
| Přeloženo Target (cíl) | Odkaz na další přeložené stránky MediaWiki | [[Special:MyLanguage/Foo|Foo]]
|
Jak přispět |
| Interwiki | Odkaz na stránku patřící jinému projektu Wikimedie |
|
Stránka dokumentace na Wikipedii |
| Externí | Odkaz na externí stránky | [https://www.example.org Example.org]
|
Example |
Šablony
Šablony se často používají na stránkách MediaWiki.org.
Šablony mohou pomoci udržet konzistenci a mohou usnadnit překlad informací.
Níže jsou uvedeny některé běžné šablony.
Šablony pro formátování stránky
- {{Caution}}, {{Fixtext}}, {{Note}}, {{Tip}}, {{Todo}}, {{Warning/core}} - pro styly vkládaných zvýrazněných polí
- {{Fixme}}, {{Historical}}, {{Notice}}, {{Zastaralé}}, {{Update}} - pro schránky zpráv na stránce/sekci
- {{Main}}, {{See also}} - pro poznámky ke stránce/sekci (krátká poznámka umístěná v horní části článku)
Šablony pro jádro MediaWiki a zdroj Git
- {{Class doclink}}, {{File doclink}}, {{Js doclink}} - odkaz na vygenerovanou dokumentaci jádra MediaWiki
- {{MW file}} - pro krabici s informacemi a odkazy na soubor v jádru MediaWiki
- {{Git file}} - pro odkaz na zdrojový kód
Šablony pro Phabricator
- {{Ptag}} - pro značku projektu Phabricator v pravém horním rohu stránky
- {{Tracked}} - pro související úlohu Phabricator
Další užitečné šablony
- {{irc|wikimedia-tech}} - pro IRC odkaz
- {{Key press}} - pro např. Ctrl+⇧ Shift+I a {{Button}} na, např. Ukázat náhled
- {{ApiEx}} - pro adresy URL požadavku api.php
- {{Api help}} - převést vygenerovanou dokumentaci API
- {{Wg}} - pro globální proměnné
- {{Tag}} - pro rychlý způsob, jak zmínit značku ve stylu XML předformátovaným způsobem
Překlady
Všechny stránky na mediawiki.org jsou kandidáty na překlad do více jazyků. MediaWiki.org je vícejazyčná wiki, používá rozšíření Translate k prezentaci alternativních překladů a správě překladu stránek.
- Pokud byla stránka přeložena, klikněte na 'Upravit zdroj' a upravte celou stránku. Špatně umístěné značky překladu kolem nadpisů sekcí mohou zmást úpravy sekcí a od července 2015 VisualEditor nerozumí následujícím značkám:
<languages>,<translate>,<tvar> - Nekopírujte a nevkládejte existující označení. Máte-li pochybnosti, zaměřte se na psaní dobrého textu a přenechejte označení Translate někomu jinému.
Související odkazy
- Některé další průvodce stylem technické dokumentace:
- Wikiversity:Technical writing
- Další jazykové zdroje: