Dokumentasi/Panduan gaya
Gambaran umum
Panduan gaya ini memberikan panduan untuk menulis dan menyunting dokumentasi teknis di MediaWiki dan ruang teknis lainnya. Panduan ini memberikan kiat-kiat menulis dokumentasi teknis yang jelas dan ringkas dalam bahasa yang sederhana. Panduan ini juga menautkan sumber daya lain mengenai penulisan dan penyuntingan teknis secara umum.
Dokumentasi teknis yang bagus memudahkan orang-orang berkontribusi ke proyek-proyek Wikimedia. Penting untuk mengikuti standar yang jelas dan panduan gaya menulis dan menyunting dokumentasi, khususnya ketika kontributor dan pembaca punya tingkat kemampuan dan pengalaman yang beragam. 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 penulisan secara umum (seperti tanda baca) secara terperinci, dan meringkas poin-poin penting dari panduan gaya lainnya. Pedoman ini bisa menjadi rujukan yang berguna bagi siapa pun yang menulis atau menyunting dokumentasi teknis dalam bahasa Inggris di proyek-proyek Wikimedia, khususnya apabila wiki lokal tidak punya panduan yang lebih spesifik.
Halaman ini menyediakan panduan dan kiat-kiat untuk membantu Anda memulai terbiasa dengan dokumentasi teknis. Halaman ini mengandung beberapa informasi spesifik mengenai dokumentasi teknis yang tidak dicakup di Pedoman Gaya Wikipedia.
Pembaca dan konten
Menulis untuk pembaca teknis
Sebelum Anda mulai menulis, pertimbangkan siapa 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 komunikasikan.
- Jika Anda tahu pembaca Anda sangat teknis dan mengenal proses yang Anda jelaskan, maka Anda tidak perlu menjelaskan konsep dasarnya.
- Jika Anda tahu pembaca Anda masih belajar atau tidak mengenal proses yang Anda jelaskan, maka masukkan penjelasan konsep dasar dan tautkan ke informasi tambahan.
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 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 berpartisipasi dalam proyek-proyek tersebut. 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. Tentu saja, pembaca ini sebaiknya memainkan peran penting dalam pembentukan dan pembentukan ulang dokumentasi ini. Pikirkan cara untuk Anda mengumpulkan informasi tentang pengalaman pengguna Anda. Luangkan waktu untuk menjawab pertanyaan berikut:
- Apakah dokumentasi Anda memiliki mekanisme untuk umpan balik?
- Bisakah Anda melakukan percakapan dengan para pembaca untuk membuat perbaikan?
- 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?
Kejelasan dan konsistensi
Kejelasan dan konsistensi membuat mengakses, membaca, dan membuat dokumentasi teknis untuk MediaWiki/Wikimedia menjadi lebih mudah. Dokumentasi teknis ditulis untuk pembaca yang luas dan disunting oleh beragam kontributor.
Suara, nada, tata bahasa, gaya, dan format sebaiknya konsisten di seluruh dokumentasi dan kumpulan konten lainnya. Ini membantu para pembaca mempelajari cara menelusuri informasi dan mempermudah kontributor memahami cara menyunting dan menambahkan informasi baru.
Menentukan jenis dokumen =
Kenali pembaca utama Anda, tujuan, dan konteks terlebih dahulu untuk memutuskan jenis dokumen yang akan Anda buat.
| 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
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. |
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
{{#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:
- Purpose of the page
- Audience of the page
- Prerequisites the reader will need to know before proceeding (Ex. a working knowledge of Python)
- Software or tools the reader will need to complete the processes or tasks outlined on the page (Ex. Java installed)
- 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
- Subheading if needed
- Content
Formatting text
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 |
| Syntax highlight |
<syntaxhighlight lang="css">
.citation {
margin: 0;
}
</syntaxhighlight>
Text before |
.citation {
margin: 0;
}
Text before |
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 See Perpanjangan:SyntaxHighlight for more details. |
| Preformatted | <pre>preformatted text
|
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}}, {{Templat:Catatan}}, or {{Warning}}.
|
| Quotations | "quotation marks"
Text before
Text after |
"quotation marks"
Text beforeText after |
Use quotation marks for brief pieces of content quoted from other sources.
Use blockquote for longer pieces of content. |
| Abbreviations | JavaScript (JS)
|
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 VisualEditor/Portal/Pintasan papan tombol.
Note: This template might not exist on other wikis. |
| Button | {{Button}}
|
Lihat pratayang | Showing UI buttons that need to be clicked on.
Note: This template might not exist on other wikis. |
Links
| Type | Purpose | How to implement | Example |
|---|---|---|---|
| Local | Link to other MediaWiki pages |
|
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 |
|
Documentation page on Wikipedia |
| External | Link to external pages | [https://www.example.org Example.org]
|
Example |
Templat
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}}, {{Templat:Catatan}}, {{Tip}}, {{Todo}}, {{Warning}} - for styles of inline highlight boxes
- {{Fixme}}, {{Templat:Arsip}}, {{Notice}}, {{Outdated}}, {{Templat:Update}} - for page/section message boxes
- {{Main}}, {{Templat: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
- {{Templat: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
- {{Templat: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. Lihat pratayang
- {{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
Terjemahan
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.
- Jika suatu halaman telah diterjemahkan, tekan 'Sunting sumber' untuk menyunting seluruh halaman. Tag penanda terjemahan yang salah diletakkan di sekitar judul bagian bisa membingungkan penyuntingan bagian, dan per Juli 2015 VisualEditor tidak mengerti tag-tag berikut:
<languages>,<translate>,<tvar> - Jangan menyalin dan menempel markah yang sudah ada. Apabila ragu, fokuslah pada menulis teks yang bagus dan biarkan orang lain mengurus markah Translate.
Lihat pula
- Some other technical documentation style guides:
- Wikiversity:Technical writing
- Other language related resources: