Documentation/Style guide/cs

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.



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.

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.



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í:

Point of view

 * Use second person ("You" or assumed "You") when addressing your audience.
 * Avoid first person ("I" or "we"), unless you are writing a FAQ with questions asked from the first person perspective.
 * Use an imperative mood for most documentation focused on goals or process.

Dates

 * Always use the full, four-digit year.
 * Use absolute dates ("in May 2037") instead of relative dates ("next year in May").
 * Avoid adding dates that will require regular manual updates. Example: Write  instead of  when referring to the current year, no matter what year it is currently.

Overview
All pages should include an overview section (also called the Lead section) that explains:


 * 1) Purpose of the page
 * 2) Audience of the page
 * 3) Prerequisites the reader will need to know before proceeding (Ex. a working knowledge of Python)
 * 4) Software or tools the reader will need to complete the processes or tasks outlined on the page (Ex. Java installed)
 * 5) Use case, case study, a practical understanding of the product, service or tool in action. (optional)

Table of contents

 * Each page should include a table of contents, so information can be accessed easily.

Titles and headings

 * Use sentence case for headings.
 * Keep heading fonts consistent throughout documentation.
 * Optional use of anchors to link sections or subsections in the same page.
 * Add a blank line after section headings. This impacts how the content is packaged for translation.
 * Do not put a heading before your overview or lead section.

Information flow
Technical documentation pages should follow a consistent pattern across content collections.

An ideal pattern for each page might be:


 * Page title
 * Introduction/Overview
 * Heading
 * Content
 * Subheading if needed
 * Content

Formatting code examples and other technical elements
Formatting distinguishes code and other technical elements from regular text.

Templates
Templates are often used on MediaWiki.org pages. Templates can help to maintain consistency and can make it easier to translate information.

Below are some common templates.

Templates for page formatting

 * caution, fixtext, note, tip, todo, warning - for styles of inline highlight boxes
 * fixme, historical, notice, outdated, update - for page/section message boxes
 * main, see also - for page/section hatnotes (a short note placed at the top of an article)

Templates for MediaWiki core and Git source

 * class doclink, file doclink, js doclink - to link to MediaWiki core's generated documentation
 * MW file - for a box with info and links for a file in MediaWiki core
 * git file - to link to source code

Templates for Phabricator

 * ptag - for the top-right-of-page Phabricator project tag
 * tracked - for the related Phabricator task

Other useful templates

 * - for IRC link
 * Key press - for, e.g. Ctrl, and button for, e.g.
 * ApiEx - for api.php request URLs
 * Api help - to transclude generated API documentation
 * RestOfVariableName - for global variables
 * tag - for a quick way to mention an XML-style tag in a preformatted way

Translations
All pages on mediawiki.org are candidates for translation into multiple languages. MediaWiki.org is a multilingual wiki, it uses the Translate extension to present alternative translations and manage the translation of pages.