Documentation/Style guide/tr

Genel bakış
Bu sayfa, MediaWiki ve diğer teknik alanlarda teknik dokümantasyon yazmak ve düzenlemek için ek bir stil kılavuzudur. Düz dilde net, özlü teknik belgeler yazmak, projeler arasında kullanılan çeşitli teknik belgeler için en iyi uygulamaları ve standartları vurgulamak, genel olarak teknik yazma ve düzenleme ile ilgili kaynakları ve bilgileri paylaşmak için ipuçları sağlamayı amaçlamaktadır.

"İyi" teknik belgeler, bireylerin Wikimedia projelerinde teknik katkılar yapmasını kolaylaştırır. Belgelerin yazılması ve düzenlenmesi için açık standartlar ve stil yönergelerine uyulması önemlidir, özellikle de birçok kişi değişik beceri ve deneyimlere katkıda bulunduğunda. 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 belirli konuları ayrıntılı olarak (noktalama işaretleri gibi) kapsar ve diğerlerinin temel noktalarını özetler. Yerel vikide daha spesifik kurallar bulunmadığında, Wikimedia projelerinde İngilizce teknik belgelendirme yazan veya düzenleyen herkes için yararlı bir kaynak olabilir.

Bu sayfada, başlamanıza yardımcı olacak temel yönergeler ve ipuçları ile Vikipedi Stil El Kitabında yer almayan bazı bilgiler verilmektedir.

Teknik izleyiciler için yazma
Yazmaya başlamadan önce, çalışmalarınız için izleyicileri düşünmek önemlidir.


 * Bu teknik belgeleri kim okuyacağını hayal ediyorsunuz?
 * Nereden geliyorlar?
 * Sunduğunuz kavramlara ne kadar aşinadır?
 * Anlamak için neleri bilmeleri gerekebilir?

Kitlenizi anladıktan sonra, neyi aktarmanız ve nasıl aktarmanız gerektiği konusunda daha iyi bir fikre sahip olacaksınız.

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 döneme, mevcut teknolojinin türüne, coğrafi konumunuza ve kültürünüze veya sizin ve okuyucularınızın ait olduğu toplumun 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, gönüllü olan bireyler tarafından oluşturulan kültürü düşünün ve bunlar arasında yer alı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
Amacınız, MediaWiki/Wikimedia için teknik belgelere erişmeyi, okumayı ve oluşturmayı daha kolay ve daha sezgisel hale getirerek netliği ve tutarlılığı teşvik etmektir. 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
Yaratacağınız belge türüne karar vermek için önce ana kitlenizi, amacınızı ve bağlamınızı belirleyin.

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.

Şablonlar
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

Ç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.

Daha fazla bilgi

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

Ayrıca bakınız

 * 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