Documentation/Style guide/id

Gambaran umum
Halaman ini merupakan panduan gaya tambahan untuk menulis dan menyunting dokumentasi teknis di MediaWiki dan ruang teknis lainnya. Panduan ini dimaksudkan untuk memberikan kiat-kiat menulis dokumentasi teknis yang jelas dan ringkas dalam bahasa yang sederhana, untuk menyoroti praktik dan standar terbaik untuk berbagai dokumen teknis yang digunakan di berbagai proyek, untuk berbagi sumber daya dan pengetahuan mengenai penulisan dan penyuntingan teknis secara umum.

Dokumentasi teknis yang bagus memudahkan orang-orang untuk membuat kontribusi teknis di proyek-proyek Wikimedia. Tidak peduli apakah Anda merasa diri Anda adalah seorang penulis atau bukan, kontribusi Anda dibutuhkan dan diapresiasi.

Pedoman Gaya Wikipedia bahasa Inggris
Pedoman Gaya Wikipedia bahasa Inggris mencakup topik-topik tertentu secara terperinci (seperti tanda baca) dan meringkas poin-poin penting dari topik lainnya. Pedoman ini bisa menjadi rujukan yang berguna bagi siapa pun yang menulis atau menyunting dokumentasi teknis dalam bahasa Inggris di proyek-proyek Wikimedia apabila tidak ada panduan spesifik di wiki lokal.

Panduan tambahan untuk penulisan dan penyuntingan teknis
Penting untuk mengikuti standar yang jelas dan panduan gaya menulis dan menyunting dokumentasi, khususnya ketika banyak orang berkontribusi dengan berbagai tingkat kemampuan dan pengalaman. Terdapat banyak gaya dan aturan penggunaan untuk penulisan umum – terlalu banyak untuk dihafal – dan lebih banyak lagi untuk penulisan teknis. Halaman ini menyediakan panduan dan kiat-kiat untuk membantu Anda memulai, serta beberapa informasi spesifik yang tidak dicakup di Pedoman Gaya Wikipedia.

Menulis untuk pembaca teknis
Sebelum Anda mulai menulis, penting untuk memikirkan pembaca karya Anda.


 * Siapa yang Anda bayangkan akan membaca dokumentasi teknis ini?
 * Dari mana asal mereka?
 * Seberapa kenal mereka dengan konsep yang Anda sampaikan?
 * Apa yang mungkin mereka perlu ketahui agar paham?

Setelah Anda paham siapa pembaca Anda, Anda harus memahami apa yang Anda perlu ungkapkan dan cara mengungkapkannya.

Menulis dengan tujuan
Tujuan apa yang akan dicapai oleh dokumentasi teknis Anda? Terdapat banyak alasan untuk menulis dokumentasi. Akan berguna untuk mengetahui mengapa Anda menulis dan apa sasaran Anda sebelum Anda memulai.


 * Apakah untuk mengajari seseorang, misalnya pendatang baru, tentang suatu proses atau konsep?
 * Apakah untuk menunjukkan seseorang cara melakukan suatu proses?
 * Apakah untuk memberikan latar belakang dan konteks untuk suatu konsep atau proses?
 * Apakah untuk dijadikan referensi yang dimaksudkan untuk memberikan informasi?

Menulis di dalam konteks
Ketika menentukan apa yang mau ditulis dan bagaimana cara menyampaikannya kepada pembaca Anda, sebaiknya Anda menetapkan konteks atau latar belakang dari tulisan Anda. Komunikasi Anda terjadi dalam suatu konteks situasi yang lebih besar. Konteksnya bisa dibatasi oleh era waktu Anda menulis, jenis teknologi yang tersedia, lokasi geografis dan budaya Anda, atau budaya dan gaya komunikasi dari komunitas Anda dan pembaca Anda. Latar belakangnya bisa jadi bersifat pribadi dan muncul dari situasi yang memotivasi Anda untuk menulis atau memperbaiki suatu dokumentasi.

Contohnya, jika Anda menulis dokumentasi teknis untuk proyek Wikimedia, pertimbangkan budaya yang dibuat oleh orang-orang yang berkontribusi, dan ikut serta bersama mereka. Bagaimana Anda sebaiknya memosisikan tulisan Anda di dalam konteks komunitas ini dan budayanya demi membuat dokumentasi teknis yang sebermakna dan seberguna mungkin?

Uji coba dan umpan balik pengguna
Buatlah dokumentasi teknis untuk mengomunikasikan gagasan dan konsep kepada pengguna pembaca yang nyata. 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?

Clarity and consistency
Your goal is to make accessing, reading, and creating technical documentation for MediaWiki/Wikimedia easier and more intuitive by promoting clarity and consistency throughout. 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.

Overview
All pages should include an overview 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.

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
Many situations call for text to be formatted in a way that 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:


 * ApiEx for api.php request URLs
 * Api help to transclude generated API documentation
 * caution, fixtext, note, tip, todo, and warning for styles of inline highlight boxes
 * fixme, historical, notice, outdated, and update for page/section message boxes
 * class doclink, file doclink, and js doclink to link to MediaWiki core's generated documentation
 * git file to link to source code
 * for IRC link
 * Key press for, e.g. Ctrl, and button for, e.g.
 * main and see also for page/section hatnotes (a short note placed at the top of an article)
 * MW file for a box with info and links for a file in MediaWiki core
 * ptag for the top-right-of-page phabricator project tag
 * tracked for the related Phabricator task
 * 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
 * Technical documentation prioritization