Jump to content

Belgelendirme/Stil kılavuzu

From mediawiki.org
This page is a translated version of the page Documentation/Style guide and the translation is 22% complete.
Outdated translations are marked like this.
Languages:

Genel bakış

Bu stil kılavuzu, MediaWiki ve diğer teknik alanlarda teknik belgelerin yazılması ve düzenlenmesi için rehberlik sağlar. Sade bir dilde net, özlü teknik belgeler yazmanıza yardımcı olacak ipuçları sağlar. Ayrıca genel olarak teknik yazı ve düzenleme ile ilgili ek kaynaklara da bağlantı verir.

İyi teknik belgeler, insanların Wikimedia projelerine katkıda bulunmasını kolaylaştırır. Özellikle katkıda bulunanlar ve okuyucular farklı düzeylerde beceri ve deneyime sahip olduğunda, belge yazmak ve düzenlemek için açık standartlar ve stil yönergelerini takip etmek önemlidir. Kendinizi bir yazar olarak düşünün ya da düşünmeyin, katkılarınıza ihtiyaç duyulur ve takdir edilir.

İngilizce Vikipedi Stil El Kitabı

İngilizce Vikipedi'nin Kullanım Kılavuzu, genel yazı konularını (noktalama işaretleri gibi) ayrıntılı olarak kapsar ve diğer stil kılavuzlarının önemli noktalarını özetler. Özellikle yerel vikinin daha spesifik yönergeleri yoksa, Wikimedia projelerinde İngilizce teknik belgeler yazan veya düzenleyen herkes için yararlı bir referans olabilir.

Bu sayfa, teknik belgelere başlamanıza yardımcı olacak temel yönergeler ve ipuçları sağlar. Vikipedi Stil El Kitabında kapsanmayan, teknik belgelere özgü bazı bilgiler içerir.

Kitle ve içerik

Teknik izleyiciler için yazma

Yazmaya başlamadan önce, çalışmanızın hedef kitlesini düşünün:

  • Bu teknik belgeleri kim okuyacak?
  • Nereden geliyorlar?
  • Sunduğunuz kavramlara ne kadar aşinadır?
  • Anlamak için neleri bilmeleri gerekebilir?

Kitlenizi anladıktan sonra, iletişim kurmanız gereken şey hakkında daha iyi bir fikre sahip olacaksınız.

  • Kitlenizin tanımladığınız süreçlere son derece teknik ve tanıdık olduğunu biliyorsanız, temel kavramları açıklamanız gerekmez.
  • Kitlenizin tanımladığınız süreçlerle öğrenme veya yabancı olduğunu biliyorsanız, temel kavramların açıklamalarını ve ek bilgilere bağlantılarını ekleyin.

Amaç ile yazma

Teknik belgeleriniz hangi amaca hizmet edecek? Belge yazmanın birçok nedeni vardır. Neden yazdığınızı ve başlamadan önce hedefinizin ne olduğunu bilmek faydalı olacaktır.

  • Birisine yeni gelen gibi bir süreç veya kavram hakkında bilgi vermek mi?
  • Birisine bir süreci nasıl takip edeceğini göstermek mi?
  • Bir kavram veya süreç için arka plan ve bağlam sağlamak mı?
  • Bilgi sağlamaya yönelik bir kaynak mı?

Bir bağlam içinde yazma

Ne yazacağınıza ve onu okuyucunuz için nasıl çerçeveleyeceğinize karar verirken, yazınız için bir bağlam veya fırsat tanımlamanıza yardımcı olabilir. İletişiminiz daha büyük bir durum bağlamında gerçekleşir. Bağlam, yazdığınız çağa, mevcut teknolojinin türüne, coğrafi konumunuza ve kültürünüze veya okuyucularınızın mevcut kültür ve iletişim tarzlarına bağlı olabilir. Bu durum kişisel olabilir ve sizi bir belge oluşturmaya veya geliştirmeye motive eden durumdan kaynaklanabilir.

Örneğin, Wikimedia projeleri için teknik belgeler yazıyorsanız, bu projelere katılan bireylerin oluşturduğu kültürü düşünün. En anlamlı ve faydalı teknik belgeleri oluşturmak için yazınızı bu topluluk ve kültürü bağlamında en iyi nasıl konumlandırabilirsiniz?

Kullanıcı testi ve geri bildirim

Fikir ve kavramları gerçek bir kullanıcı kitlesine iletmek için teknik belgeler oluşturun. Doğal olarak, bu kitle belgelerin şekillendirilmesi ve yeniden şekillendirilmesinde kritik bir rol oynamalıdır. Kullanıcılarınızın deneyimleri hakkında bilgi toplamanın yollarını düşünün. Aşağıdaki soruları cevaplamak için biraz zaman ayırın:

  • Belgeleriniz bir geri bildirim mekanizması içeriyor mu?
  • Geliştirmeler yapmak için kitle ile zamanında görüşme yapabilir misiniz?
  • 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?

Netlik ve tutarlılık

Netlik ve tutarlılık, MediaWiki/Wikimedia projelerinde teknik belgelere erişmeyi, bunları okumayı ve oluşturmayı kolaylaştırır. Teknik belgeler geniş bir kitle için yazılmıştır ve çeşitli katılımcılar tarafından düzenlenmiştir.

Ses, ton, dilbilgisi kullanımı, stil ve biçim, teknik belgeler ve benzer içerik koleksiyonları arasında tutarlı olmalıdır. Bu, okuyucuların bilgiler arasında nasıl gezineceğini öğrenmelerine yardımcı olur ve katkıda bulunanların yeni bilgileri nasıl düzenleyeceklerini ve ekleyeceklerini anlamalarını kolaylaştırır.

Belge türüne karar verme

Ayrıca bakınız: Documentation/Technical documentation templates and suggestions


Yaratacağınız belge türüne karar vermek için önce ana kitlenizi, amacınızı ve bağlamınızı belirleyin.

Example Audience Purpose[1] Potential Document Types Example
Newcomer interested in learning how to become a Toolforge user To learn Tutorial, FAQ, Getting Started guide Cloud VPS and Toolforge FAQ
Experienced technical contributor trying to work through a known problem To achieve a goal Walk-through, How-To guide My First Flask OAuth Tool
Individual trying to understand the history of ORES and how it evolved To understand Explanatory article, blog post, "overview" Artificial intelligence service “ORES” gives Wikipedians X-ray specs to see through bad edits
A person looking for a definition of SSH keys To inform Reference guide, glossary Glossary

Language

Ayrıca bakınız: The "Writing clearly" article on Wikiversity


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 (also called plain language) 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.

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

Voice and tone What this means Instead of this Try This
Friendly Technical documentation does not need to sound academic or dry. Write to your audience as if they are there in person. Before beginning, the user must create an account. Start by creating an account.
Professional Technical documentation can be friendly, but should remain professional. Use Inclusive language . Don't make a bazillion changes. Try to make minimum changes.
Positive Avoid using negative sentence constructions. Explain things in terms of what to do. It is harder to mentally parse a complex negative sentence! N won't happen, if you don't XYZ. To make N happen, do XYZ.
Active Try to use active voice, except when diplomacy calls for passive voice. The extension must be registered. You must register the extension.
Non-gendered Adopt gender-inclusive language. Assume your audience comprises all gender identities. When he clicks Save When the user clicks Save
Inclusive Use alternatives to common words or phrases that may unintentionally reinforce inappropriate stereotypes. This UI is crazy. This UI could be improved.
Free of frustration Avoid terms like "easy" and "simple" which can be frustrating for less tech-savvy users. Simply create a user account. Create a user account.
Free of colloquialisms It can be confusing to use colloquialisms, jokes, puns, or turns of phrase that non-native English speakers or individuals from other regions might not easily understand. Creating a user account is a piece of cake. Creating a user account requires two steps.
This is not meant to be an exhaustive list or a strict set of rules.

Point of view

The following guidance overrides the general Wikipedia style guidelines for pronouns, but only for technical documentation.
  • 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 {{#time: Y }} instead of 2024 when referring to the current year, no matter what year it is currently.

Structuring pages

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

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 text

Anasayfa: Help:Formatting

Formatting code examples and other technical elements

Formatting distinguishes code and other technical elements from regular text.

Purpose Wiki-Markup Result Situation
Code ‎<code>code‎</code> code Use for short strings of code, including wikitext markup.

Within ‎<code>...‎</code>, use ''italics'' to indicate variables and sample names so users know what to replace.

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

Text before <syntaxhighlight lang="css" inline>.foo {margin: 0;}</syntaxhighlight> text after. 

.citation {
    margin: 0;
}

Text before .foo {margin: 0;} text after.

Use the ‎<syntaxhighlight lang="...">...‎</syntaxhighlight> tag to document a few lines of code, and preserve whitespace and linebreaks. The inline attribute allows using it within an existing paragraph.

Note you cannot use italic in the middle of a <syntaxhighlight lang="foo">...</syntaxhighlight> block, so you have to fall back to YOURPASSWORD or The_page_title to indicate variables.

See Extension:SyntaxHighlight for more details.

Preformatted ‎<pre>preformatted text
      with indent‎</pre> 
preformatted text
      with indent
 Same as above (preserve whitespace and linebreaks), but without coloring.
Keyboard input ‎<kbd>keyboard 123‎</kbd> (vs keyboard 123) keyboard 123 (vs keyboard 123) Use ‎<kbd>...‎</kbd> for actual keyboard input - the text a user types into an input field or at a terminal command line. It displays in plain monospace.
Variables ‎<var>variable‎</var> 
''italics''
variable

italics

Use italics for variables like message-key-name and sample names like My page title.

Do not use punctuation such as <YOURPASSWORD>, because readers don't know the angle brackets are noise and will type them.

Bold 
'''bold'''
bold Generally only used for the first instance of the page-title, and for rare emphasis of keywords to enable easier skimming of lists or paragraphs.
Sometimes bold is overused for emphasis. You may consider using a template instead, e.g. {{Caution }}, {{Note }}, or {{Warning/core }}.
Quotations "quotation marks"

Text before

‎<blockquote>blockquote‎</blockquote>

Text after

"quotation marks" Text before

blockquote

Text after 		Use quotation marks for brief pieces of content quoted from other sources.

Use blockquote for longer pieces of content.

Abbreviations JavaScript (JS)

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

JavaScript (JS)

JS

You should define abbreviations the first time they are used. Use either plain text and parentheses, or the HTML abbr tag.
Keypress {{Key press }} Ctrl+⇧ Shift+I Showing specific keyboard presses or combinations. Extensive examples in Görsel Düzenleyici/Portal/Klavye kısayolları .

Note: This template might not exist on other wikis.

Button {{Button }} Önizlemeyi göster Showing UI buttons that need to be clicked on.

Note: This template might not exist on other wikis.


Anasayfa: Help:Links
Type Purpose How to implement Example
Local Link to other MediaWiki pages
  • [[Foo]]
  • [[Foo|Bar]]
 MediaWiki
Translated Target Link to other translated MediaWiki pages [[Special:MyLanguage/Foo|Foo]] How to contribute
Interwiki Link to page belonging to a different Wikimedia project
  • [[phab:T2001]] for tasks and project tags
  • [[mail:wikitech-l]] for mailing lists
  • [[w:en:foobar]] to English Wikipedia articles
  • [[wikitech:foobar]] for details about the WMF cluster
  • [[gerrit:604435]] for change requests in Gerrit
Documentation page on Wikipedia
External Link to external pages [https://www.example.org Example.org] Example

Şablonlar

Ayrıca bakınız: Documentation/Style guide/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

Templates for MediaWiki core and Git source

Templates for Phabricator

  • {{Ptag }} - for the top-right-of-page Phabricator project tag
  • {{Tracked }} - for the related Phabricator task

Other useful templates

  • {{irc|wikimedia-tech}} - for IRC link
  • {{Key press }} - for, e.g. Ctrl+⇧ Shift+I, and {{Button }} for, e.g. Önizlemeyi göster
  • {{ApiEx }} - for api.php request URLs
  • {{Api help }} - to transclude generated API documentation
  • {{Wg }} - for global variables
  • {{Tag }} - for a quick way to mention an XML-style tag in a preformatted way

Çeviriler

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.

  • Bir sayfa çevrildiyse, sayfanın tamamını düzenlemek için 'Kaynağı düzenle'yi tıklayın. Yanlış yerleştirilmiş bölüm başlıklarının etrafındaki çeviri etiketi işaretleri bölüm düzenlemeyi karıştırabilir ve Temmuz 2015 itibariyle Görsel Düzenleyici aşağıdaki etiketleri anlamıyor: ‎<languages>, ‎<translate>, ‎<tvar>
  • Mevcut biçimlendirmeyi kopyalayıp yapıştırmayın. Şüpheniz varsa, iyi bir metin yazmaya odaklanın ve bir başkasının Çeviri işaretlemesini yapmasına izin verin.

Ayrıca bakınız

Dipnotlar

  1. ↑ https://www.divio.com/en/blog/documentation/
Retrieved from "https://www.mediawiki.org/w/index.php?title=Documentation/Style_guide/tr&oldid=6652995"