Panduan pemformatan teks

Penggunaan gaya berani, miring, dan kode yang konsisten dan sesuai untuk elemen teks meningkatkan keterbacaan dan membantu menghindari kesalahpahaman. Jika elemen pemformatan teks tidak dibahas oleh panduan ini, lihat Panduan Gaya Penulisan Microsoft. Artikel berikut ini menyediakan panduan terperinci tentang pemformatan teks:

• Memformat elemen teks umum

• Memformat teks dalam instruksi

• Memformat elemen pengembang umum

Elemen antarmuka pengguna

Elemen UI, seperti item menu, nama dialog, dan nama kotak teks, harus dalam teks tebal.

• Ini: Di Penjelajah Solusi, klik kanan simpul proyek, lalu pilih Tambahkan>Item Baru.

• Bukan ini: Dalam Penjelajah Solusi, klik kanan simpul proyek, lalu pilih Tambahkan > Item Baru.

Nama repositori dan cabang Git

Gunakan teks tebal untuk repositori Git atau nama cabang saat dipilih atau dimasukkan dalam instruksi.

• Ini: Dari menu cabang, pilih utama.

• Bukan ini: Dari menu cabang, pilih "utama".

Pengenalan istilah baru

Gunakan teks miring untuk memperkenalkan istilah baru bersama dengan definisi atau penjelasan. Miringkan istilah baru saat pertama kali Anda menggunakannya, lalu gunakan teks biasa untuk definisi atau penjelasannya.

• Ini: Di App Service, aplikasi berjalan dalam paket App Service. Paket App Service menentukan satu set sumber daya komputasi untuk menjalankan aplikasi web.

• Bukan ini: Di App Service, aplikasi berjalan dalam "paket App Service." Paket App Service menentukan sekumpulan sumber daya komputasi untuk menjalankan aplikasi web.

Gaya Kode

Gunakan gaya kode untuk:

• Elemen kode, seperti nama metode, nama properti, dan kata kunci bahasa.
• Perintah SQL
• Nama paket NuGet
• Perintah baris perintah*
• Nama tabel dan kolom database
• Nama sumber daya yang tidak boleh dilokalkan (seperti nama komputer virtual)
• URL yang tidak ingin Anda klik

Mengapa? Beberapa panduan gaya menentukan tebal untuk banyak elemen teks ini. Namun, sebagian besar artikel dilokalkan, dan gaya kode memberi tahu penerjemah untuk membiarkan bagian teks tersebut tidak diterjemahkan.

Gaya kode dapat sebaris (dikelilingi oleh ') atau blok kode pagar (dikelilingi oleh ''') yang mencakup beberapa baris. Letakkan cuplikan kode dan jalur yang lebih panjang di blok kode pagar.

* Dalam perintah baris perintah, gunakan garis miring di jalur file jika didukung di semua platform. Gunakan garis miring terbelakang untuk mengilustrasikan perintah yang berjalan di Windows, ketika hanya garis miring terbelakang yang didukung. Misalnya, garis miring ke depan berfungsi pada .NET CLI di semua platform, sehingga Anda akan menggunakan dotnet build foldername/filename.csproj daripada dotnet build foldername\filename.csproj.

Contoh menggunakan gaya sebaris

• Ini: Secara default, Kerangka Kerja Entitas menginterpretasikan properti yang dinamai Id atau ClassnameID sebagai kunci utama.
• Bukan ini: Secara default, Kerangka Kerja Entitas menginterpretasikan properti yang bernama Id atau ClassnameID sebagai kunci utama.
• Ini: Paket ini Microsoft.EntityFrameworkCore menyediakan dukungan runtime untuk EF Core.
• Bukan ini: Paket Microsoft.EntityFrameworkCore menyediakan dukungan runtime untuk EF Core.

Contoh blok kode yang dipagari

• Ini: Tidak ada perintah yang dikirim ke database berdasarkan pernyataan yang hanya mengubah IQueryable, seperti kode berikut:

      ```csharp
      var students = context.Students.Where(s => s.LastName == "Davolio")
      ```
  

• Bukan ini: Tidak ada perintah yang dikirim ke database berdasarkan pernyataan yang hanya mengubah IQueryable, seperti siswa var = konteks. Students.Where(s => s.LastName == "Davolio").

• Ini: Misalnya, untuk menjalankan Get-ServiceLog.ps1 skrip di C:\Scripts direktori, ketik:

      ```powershell
      C:\Scripts\Get-ServiceLog.ps1
      ```
  

• Bukan ini: Misalnya, untuk menjalankan skrip Get-ServiceLog.ps1 di direktori C:\Scripts , ketik: "C:\Scripts\Get-ServiceLog.ps1."

• Semua blok kode yang dipagari harus memiliki tag bahasa yang disetujui. Untuk daftar tag bahasa dukungan, lihat Cara menyertakan kode dalam dokumen.

Tempat penampung

Dalam teks paragraf atau langkah-langkah prosedural, gunakan huruf miring untuk teks pengganti yang akan diganti oleh pengguna dengan informasi mereka sendiri.

• Ini: Masukkan kata sandi

• Bukan ini: Masukkan "kata sandi"

• Ini: Masukkan kata sandi-p

• Bukan ini: Masukkan kata sandi -p

Jika Anda ingin pengguna mengganti bagian dari string input dengan nilainya sendiri, gunakan teks tempat penampung yang ditandai dengan tanda kurung sudut (kurang dari < dan lebih besar dari > karakter).

Opsi 1: Gunakan gaya kode untuk mengelilingi kata tempat penampung atau frasa yang mencakup. Misalnya, Anda dapat menggunakan backtick tunggal ' untuk pemformatan kode sebaris untuk satu frasa, atau triple-ticks ''' untuk pemformatan berpagar kode.

`az group delete -n <ResourceGroupName>`

Dirender sebagai:

az group delete -n <ResourceGroupName>

atau

Opsi 2: Gunakan karakter \ garis miring terbalik untuk menghindari karakter tanda kurung sudut di Markdown, seperti \< dan \>. Meskipun hanya escape pertama di braket \< sudut kiri yang diperlukan, melarikan diri dari braket \> penutup juga berfungsi untuk konsistensi. HTML yang dirender tidak menampilkan karakter escape kepada pembaca:

az group delete -n \<ResourceGroupName\>

Dirender sebagai:

az group delete -n <ResourceGroupName>

Beri tahu pembaca tentang tempat penampung: Dalam teks yang mendahului contoh tempat penampung, jelaskan kepada pembaca bahwa teks dalam tanda kurung harus dihapus dan diganti dengan nilai nyata. Kami merekomendasikan penggunaan miring untuk input pengguna. Anda dapat memformat miring dalam kode sebaris kurung sudut:

Dalam contoh berikut, ganti teks <ResourceGroupName> tempat penampung dengan nama grup sumber daya Anda sendiri.

Perhatian

Situs Microsoft Learn tidak merender <teks tempat penampung> yang menggunakan tanda kurung sudut dalam kasus di mana tanda kurung tidak lolos dengan benar atau teks tidak diformat kode. Proses build Microsoft Learn menginterpretasikan <frasa tempat penampung> sebagai tag HTML yang bisa berbahaya bagi browser pembaca, dan menandainya sebagai tag-html yang tidak diizinkan. Anda akan melihat saran dalam laporan build, dan kata tempat penampung tidak dirender dalam output halaman Microsoft Learn saat itu terjadi.

Untuk menghindari kehilangan konten pada tempat penampung, gunakan code karakter pemformatan atau escape (\<\>) seperti yang dijelaskan sebelumnya.

Kami mencegah penggunaan kurung kurawal { } sebagai tempat penampung sintis. Pembaca dapat membingungkan tempat penampung kurung kurawal dengan notasi yang sama yang digunakan dalam:

• Teks yang dapat diganti
• String format
• Interpolasi string
• Templat teks
• Konstruksi pemrograman serupa

Casing dan spasi: Anda dapat memisahkan nama tempat penampung dengan tanda hubung ("kasus kebab") atau dengan garis bawah, atau Anda dapat melakukannya dengan menggunakan kasus Pascal. Kasus Kebab mungkin menghasilkan kesalahan sintaksis, dan garis bawah dapat bertentangan dengan garis bawah. Penggunaan huruf kapital dapat bertentangan dengan konstanta yang dinamai dalam banyak bahasa, meskipun mungkin juga menarik perhatian pada nama placeholder.

<Resource-Group-Name> atau <ResourceGroupName>

Judul-judul

Jangan terapkan gaya sebaris seperti gaya kode miring, tebal, atau sebaris ke judul.

Mengapa? Judul memiliki gayanya sendiri, dan mencampur gaya lain menciptakan inkonsistensi.

• Ini: Mengimpor paket Microsoft.NET.Sdk.Functions

• Bukan ini: Impor paket Microsoft.NET.Sdk.Functions

Teks tautan

Jangan terapkan gaya sebaris seperti miring atau tebal untuk menautkan teks.

Mengapa? Orang mengandalkan teks hyperlink standar untuk mengidentifikasi elemen teks sebagai tautan yang dapat diklik. Memformat tautan sebagai miring, misalnya, dapat mengaburkan fakta bahwa teks tersebut merupakan tautan.

• Ini: Paket NuGet Microsoft.NET.Sdk.Functions menghasilkan file function.json.

Bukan ini: Paket NuGet Microsoft.NET.Sdk.Functions menghasilkan file function.json.

Tombol dan pintasan keyboard

Saat merujuk ke kunci atau kombinasi kunci, ikuti konvensi berikut:

• Kapitalkan huruf pertama nama kunci.
• Kelilingi nama kunci dengan <kbd> tag HTML.</kbd>
• Gunakan "+" untuk menggabungkan kunci yang dipilih pengguna secara bersamaan.

Contoh tombol dan pintasan keyboard

• Ini: Pilih Alt+Ctrl+S.
• Bukan ini: Tekan ALT+CTRL+S.
• Bukan ini: Tekan ALT+CTRL+S.

Pengecualian

Pedoman gaya yang konsisten menciptakan pengalaman pelanggan yang andal dan menyederhanakan proses penulisan. Pengecualian untuk pedoman ini harus dipertimbangkan dengan hati-hati.

Jika pengecualian melibatkan penggunaan gaya teks alternatif yang biasanya memanggil kode, pastikan tidak masalah untuk menerjemahkan teks dalam versi artikel yang dilokalkan. Untuk skenario di mana Anda ingin mencegah pelokalan tanpa menggunakan gaya kode, lihat String yang tidak dilokalkan.