Documentation/Style guide/ru

Обзор
Это руководство по стилю предоставляет рекомендации по написанию и редактированию технической документации в MediaWiki и других технических пространствах. Он содержит советы, которые помогут вам написать четкую, краткую техническую документацию простым языком. Он также содержит ссылки на дополнительные ресурсы по техническому написанию и редактированию в целом.

Good technical documentation makes it easier for people to contribute to Wikimedia projects. It is important to follow clear standards and style guidelines for writing and editing documentation, especially when the contributors and readers have varying levels of skills and experience. Whether or not you consider yourself a writer, your contributions are needed and appreciated!

English Wikipedia Manual of Style
The English Wikipedia's Manual of style covers general writing topics (like punctuation) in detail, and summarizes the key points of other style guides. It can be a useful reference for anyone writing or editing technical documentation in English across Wikimedia projects, especially if the local wiki doesn't have more specific guidelines.

This page provides basic guidelines and tips to help get you started with technical documentation. It includes some information specific to technical documentation that is not covered in the Wikipedia Manual of Style.

Writing for technical audiences
Before you begin writing, consider the audience for your work:

Кто будет читать эту техническую документацию?
 * Where are they coming from?
 * How familiar are they with the concepts you are presenting?
 * What might they need to know in order to understand?

Как только у вас появится понимание вашей аудитории, у вас будет лучшее смысл о том, что вам нужно сообщить.

Writing with a purpose
What purpose will your technical documentation serve? There are many reasons to write documentation. It is helpful to know why you are writing and what your goal is before you begin.


 * Is it to teach someone, like a newcomer, about a process or concept?
 * Is it to show someone how to follow a process?
 * Is it meant to provide background and context for a concept or process?
 * Is it a reference intended to provide information?

Writing within a context
When deciding what to write and how to frame it for your reader, it can help to define a context or occasion for your writing. Your communication takes place in the context of a bigger situation. Контекст может быть ограничен эпохой, в которую вы пишете, типом доступных технологий, вашим географическим положением и культурой или текущей культурой и стилями общения ваших читателей. The occasion may be personal and arise from the situation that motivated you to create or improve a piece of documentation.

Например, если вы пишете техническую документацию для проектов Викимедиа, учитывайте культуру созданную людьми, которые участвуют в этих проектах. How could you best position your writing within the context of this community and its culture to create the most meaningful and useful technical documentation?

User testing and feedback
Create technical documentation to communicate ideas and concepts to a real audience of users. Naturally, this audience should play a critical role in how the documentation is shaped and reshaped. Think about ways you can gather information about your users' experiences. Take some time to answer the following questions:


 * Does your documentation include a mechanism for feedback?
 * Can you engage in timely conversations with the audience to make improvements?
 * Can you use forums like Stack Overflow or mailing lists to check if your document answers the most common questions people have about your specific topic?

Clarity and consistency
Ясность и последовательность облегчает доступ, чтение и создание технической документации в проектах MediaWiki / Wikimedia. Technical documentation is written for a wide audience and edited by a variety of contributors.

Voice, tone, grammar usage, style, and format should be consistent across technical documentation and similar content collections. This helps readers learn how to navigate information and makes it easier for contributors to understand how to edit and add new information.

Deciding on a document type
Identify your main audience, purpose, and context first to decide on the type of document you will create.

Language
This section briefly mentions some topics worth exploring elsewhere in more detail. Always check your words and expressions against these criteria on Wiktionary: Wiktionary entries cover hundreds of languages, explicitly state the grammatical and lexical features of words and their declensions, provide detailed context labels (including about jargon, UK vs. USA English) and expose how translatable terms are in hundreds of other languages.

Plain English
Please remember: many visitors to these pages are not native English speakers.

For documentation written in English, Plain English works best. Clear writing is the most understandable by diverse audiences, and is also easiest to translate. There are a number of good tools for checking your writing, at Tech News' Writing Guidelines on Meta-Wiki.

Tips:


 * Avoid ambiguity, jargon, and vague or complex wording.
 * Use words your audience will understand, and enough words to convey your message.
 * Define terms that may not be obvious to individuals who are new to the subject matter you are writing about.
 * Keep paragraphs and sentences short and concise.
 * Use contractions or don't. Be consistent.

Voice and tone
MediaWiki is a place where anyone can edit. Thus, it can be difficult to maintain a consistent voice and tone in the documentation.

Consider using these elements in your writing:

Point of view

 * Use second person ("You" or assumed "You") when addressing your audience.
 * Avoid first person ("I"), 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 headers

 * Use sentence case for headers.
 * Keep header fonts consistent throughout documentation.
 * Optional use of anchors to link sections or subsections in the same page.
 * Add a blank line after section headers. This impacts how the content is packaged for translation.
 * Do not put a header 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
 * Header
 * Content
 * Subhead 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, and warning for styles of inline highlight boxes
 * fixme, historical, notice, outdated, and update for page/section message boxes
 * main and 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, and 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.

Further information

 * Documentation/Technical writer guide
 * Documentation/Technical documentation prioritization

См. также

 * Some other technical documentation style guides:
 * Google Developer Documentation Style Guide
 * MDN Web Docs Writing Style Guide
 * Technical writing
 * Other language related resources:
 * Inclusive language
 * Google Word List
 * Naming things