Dokumentace/Průvodce stylem

From mediawiki.org
This page is a translated version of the page Documentation/Style guide and the translation is 100% complete.

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ů Wikimedie. 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é!

Anglický Wikipedia Manual of Style

English Wikipedia's Manual of style 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 Wikimedie, 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 Wikimedie, 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.
Toto není myšleno jako vyčerpávající seznam nebo striktní soubor pravidel.

Úhel pohledu

Následující pokyny mají přednost před obecnými pokyny pro styl Wikipedie pro pronouns, ale pouze pro technickou dokumentaci.
  • 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:

  1. Účel stránky
  2. Publikum stránky
  3. Předpoklady, které musí čtenář znát, než bude pokračovat (např. pracovní znalost Pythonu)
  4. Software nebo nástroje, které bude čtenář potřebovat k dokončení procesů nebo úkolů uvedených na stránce (např. nainstalovaná Java)
  5. 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

Formátování textu

Hlavní stránka: Help:Formatting

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 ‎<code>...‎</code> použijte ''kurzíva'' k označení proměnných a názvů vzorků, aby uživatelé věděli, co mají nahradit.

Syntax highlight
<syntaxhighlight lang="css">
.citation {
    margin: 0;
}
</syntaxhighlight>

Text před <syntaxhighlight lang="css" inline>.foo {margin: 0;}</syntaxhighlight> text za.

.citation {
    margin: 0;
}

Předcházející text .foo {margin: 0;} následují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 <syntaxhighlight lang="foo">...</syntaxhighlight> nemůžete použít kurzívu, takže k označení proměnných se musíte vrátit k YOURPASSWORD nebo The_page_title.

Další podrobnosti najdete na stránce Rozšíření:SyntaxHighlight .

Preformatted ‎<pre>preformatted text
      with indent‎</pre>
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}}.
Quotations "quotation marks"

Předcházející text

‎<blockquote>blockquote‎</blockquote>

Následující text

"quotation marks" Text before

blockquote

Text after
Pro krátké části obsahu citované z jiných zdrojů používejte uvozovky.

Pro delší části obsahu použijte blockquote.

Abbreviations JavaScript (JS)

<abbr title="JavaScript">JS</abbr>

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

Hlavní stránka: Help:Links
Typ Účel Jak implementovat Příklad
Místní Odkaz na jiné stránky MediaWiki
  • [[Foo]]
  • [[Foo|Bar]]
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
  • [[phab:T2001]] pro úkoly a štítky projektu
  • [[mail:wikitech-l]] pro seznamy adresátů
  • [[w:en:foobar]] na články anglické Wikipedie
  • [[wikitech:foobar]] podrobnosti o clusteru WMF
  • [[gerrit:604435]] pro žádosti o změnu v Gerrit
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

Šablony pro jádro MediaWiki a zdroj Git

Š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

Poznámky pod čarou