Panduan dokumentasi — MRTK2

MRTK

Dokumen ini menguraikan pedoman dan standar dokumentasi untuk Mixed Reality Toolkit (MRTK). Ini memberikan pengantar aspek teknis penulisan dan pembuatan dokumentasi, untuk menyoroti jepitan umum, dan untuk menggambarkan gaya penulisan yang direkomendasikan.

Halaman itu sendiri seharusnya berfungsi sebagai contoh, oleh karena itu menggunakan gaya yang dimaksudkan dan fitur markup yang paling umum dari dokumentasi.


Fungsionalitas dan markup

Bagian ini menjelaskan fitur yang sering diperlukan. Untuk melihat cara kerjanya, lihat kode sumber halaman.

  1. Daftar bernomor
    1. Daftar bernomor berlapis dengan setidaknya 3 spasi kosong di depannya
    2. Angka aktual dalam kode tidak relevan; penguraian akan mengurus pengaturan nomor item yang benar.
  • Daftar poin poin
    • Daftar poin poin berlapis
  • Teks dalam huruf tebal dengan **tanda bintang ganda**
  • teksmiring dengan _garis bawah_ atau *tanda bintang tunggal*
  • Teks highlighted as code dalam kalimat 'menggunakan backquotes'
  • Tautan ke halaman dokumen panduan dokumentasi MRTK
  • Tautan ke jangkar dalam halaman; jangkar dibentuk dengan mengganti spasi dengan tanda hubung, dan mengonversi ke huruf kecil

Untuk sampel kode, kami menggunakan blok dengan tiga backtick ''' dan menentukan csharp sebagai bahasa untuk penyorotan sintaks:

int SampleFunction(int i)
{
   return i + 42;
}

Saat menyebutkan kode dalam kalimat use a single backtick.

Todos

Hindari menggunakan TODO dalam dokumen, karena seiring waktu TODO ini (seperti TODO kode) cenderung terakumulasi dan informasi tentang bagaimana mereka harus diperbarui dan mengapa hilang.

Jika benar-benar perlu menambahkan TODO, ikuti langkah-langkah berikut:

  1. Ajukan masalah baru pada Github yang menjelaskan konteks di balik TODO, dan berikan latar belakang yang cukup sehingga kontributor lain akan dapat memahami dan kemudian mengatasi TODO.
  2. Referensikan URL masalah dalam todo di dokumen.

<!-- TODOhttps://github.com/microsoft/MixedRealityToolkit-Unity/issues/ISSUE_NUMBER_HERE: Pengaburan singkat tentang masalah ini -->

Bagian yang disorot

Untuk menyoroti poin tertentu kepada pembaca, gunakan > [! CATATAN] , > [! PERINGATAN] , dan > [! PENTING] untuk menghasilkan gaya berikut. Disarankan untuk menggunakan catatan untuk poin umum dan peringatan/poin penting hanya untuk kasus khusus yang relevan.

Catatan

Contoh catatan

Peringatan

Contoh peringatan

Penting

Contoh komentar penting

Tata letak halaman

Pengantar

Bagian tepat setelah judul bab utama harus berfungsi sebagai pengantar singkat tentang apa bab tersebut. Jangan buat ini terlalu lama, sebagai gantinya tambahkan sub judul. Ini memungkinkan untuk menautkan ke bagian dan dapat disimpan sebagai bookmark.

Tubuh utama

Gunakan judul dua tingkat dan tiga tingkat untuk menyusun sisanya.

Bagian Mini

Gunakan baris teks tebal untuk blok yang seharusnya menonjol. Kami mungkin mengganti ini dengan judul empat tingkat di beberapa titik.

Bagian 'Lihat juga'

Sebagian besar halaman harus diakhir dengan bab yang disebut Lihat juga. Bab ini hanyalah daftar poin yang menunjuk tautan ke halaman yang terkait dengan topik ini. Tautan ini mungkin juga muncul dalam teks halaman jika sesuai, tetapi ini tidak diperlukan. Demikian pula, teks halaman mungkin berisi tautan ke halaman yang tidak terkait dengan topik utama, ini tidak boleh disertakan dalam daftar Lihat juga . Lihat bab ''Lihat juga' halaman ini sebagai contoh untuk pilihan tautan.

Daftar Isi (TOC)

File toc digunakan untuk menghasilkan bilah navigasi dalam dokumentasi MRTK github.io. Setiap kali file dokumentasi baru ditambahkan, pastikan bahwa ada entri untuk file tersebut di salah satu file toc.yml folder dokumentasi. Hanya artikel yang tercantum dalam file toc yang akan muncul di navigasi dokumen pengembang. Mungkin ada file toc untuk setiap subfolder di folder dokumentasi yang dapat ditautkan ke file toc yang ada untuk menambahkannya sebagai subbagian ke bagian navigasi yang sesuai.

Gaya

Gaya penulisan

Aturan umum praktis: Cobalah untuk terdengar profesional. Itu biasanya berarti untuk menghindari 'nada percakapan'. Cobalah juga untuk menghindari hiperbole dan sensasalisme.

  1. Jangan mencoba untuk menjadi (terlalu) lucu.
  2. Jangan pernah menulis 'I'
  3. Hindari 'kami'. Ini biasanya dapat diulang dengan mudah, menggunakan 'MRTK' sebagai gantinya. Contoh: "kami mendukung fitur ini" -> "MRTK mendukung fitur ini" atau "fitur berikut didukung ...".
  4. Demikian pula, cobalah untuk menghindari 'Anda'. Contoh: "Dengan perubahan sederhana ini, shader Anda menjadi dapat dikonfigurasi!" -> "Shader dapat dibuat dapat dikonfigurasi dengan sedikit upaya."
  5. Jangan gunakan 'frasa ceroboh'.
  6. Hindari terdengar terlalu bersemangat, kita tidak perlu menjual apa pun.
  7. Demikian pula, hindari terlalu dramatis. Tanda seru jarang diperlukan.

Kapitalisasi

  • Gunakan Kasus kalimat untuk judul. Ie. kapitalkan huruf pertama dan nama, tetapi tidak ada yang lain.
  • Gunakan bahasa Inggris biasa untuk segala sesuatu yang lain. Itu berarti tidak memanfaatkan kata-kata arbitrer, bahkan jika mereka memegang arti khusus dalam konteks itu. Lebih suka teks miring untuk menyoroti kata-kata tertentu, lihat di bawah ini.
  • Ketika tautan disematkan dalam kalimat (yang merupakan metode pilihan), nama bab standar selalu menggunakan huruf kapital, sehingga melanggar aturan tidak ada kapitalisasi sewenang-wenang di dalam teks. Oleh karena itu gunakan nama tautan kustom untuk memperbaiki kapitalisasi. Sebagai contoh, berikut adalah tautan ke dokumentasi kontrol terikat .
  • Lakukan kapitalisasi nama, seperti Unity.
  • JANGAN memanfaatkan huruf besar "editor" saat menulis editor Unity.

Penekanan dan penyorotan

Ada dua cara untuk menekankan atau menyoroti kata-kata, membuatnya tebal atau membuatnya miring. Efek teks tebal adalah teks tebal mencuat dan oleh karena itu dapat dengan mudah diperhatikan saat skimming sepotong teks atau bahkan hanya menggulir halaman. Tebal sangat bagus untuk menyoroti frasa yang harus diingat orang. Namun, gunakan teks tebal jarang, karena umumnya mengganggu.

Seringkali seseorang ingin 'mengelompokkan' sesuatu yang dimiliki secara logis bersama-sama atau menyoroti istilah tertentu, karena memiliki arti khusus. Hal-hal seperti itu tidak perlu menonjol dari keseluruhan teks. Gunakan teks miring sebagai metode ringan untuk menyoroti sesuatu.

Demikian pula, ketika nama file, jalur atau entri menu disebutkan dalam teks, lebih suka membuatnya miring untuk mengelompokkannya secara logis, tanpa mengganggu.

Secara umum, cobalah untuk menghindari penyorotan teks yang tidak perlu. Istilah khusus dapat disorot sekali untuk membuat pembaca menyadari, jangan mengulangi penyorotan seperti itu di seluruh teks, ketika tidak melayani tujuan lagi dan hanya mengalihkan perhatian.

Menyebutkan entri menu

Saat menyebutkan entri menu yang harus diklik pengguna, konvensi saat ini adalah: Project > Files > Create > Leaf

Sisipkan tautan berguna sebanyak mungkin ke halaman lain, tetapi setiap tautan hanya sekali. Asumsikan pembaca mengklik setiap tautan di halaman, dan pikirkan tentang bagaimana mengganggunya, jika halaman yang sama terbuka 20 kali.

Lebih suka tautan yang disematkan dalam kalimat:

  • BURUK: Panduan berguna. Lihat bab ini untuk detailnya.
  • GOOD: Pedoman berguna.

Hindari tautan eksternal, tautan tersebut dapat menjadi kedaluarsa atau berisi konten berhak cipta.

Saat menambahkan tautan, pertimbangkan apakah tautan juga harus dicantumkan di bagian Lihat juga . Demikian pula, periksa apakah tautan ke halaman baru harus ditambahkan ke halaman yang ditautkan ke.

Gambar / cuplikan layar

Gunakan cuplikan layar dengan hemat. Mempertahankan gambar dalam dokumentasi adalah banyak pekerjaan, perubahan UI kecil dapat membuat banyak cuplikan layar kedaluarsa. Aturan berikut akan mengurangi upaya pemeliharaan:

  1. Jangan gunakan cuplikan layar untuk hal-hal yang dapat dijelaskan dalam teks. Terutama, jangan pernah cuplikan layar kisi properti untuk tujuan tunggal menampilkan nama dan nilai properti.
  2. Jangan sertakan hal-hal dalam cuplikan layar yang tidak relevan dengan apa yang ditampilkan. Misalnya, ketika efek penyajian ditampilkan, buat cuplikan layar viewport, tetapi kecualikan UI apa pun di sekitarnya. Menampilkan beberapa UI, cobalah untuk memindahkan jendela singgah sehingga hanya bagian penting yang ada dalam gambar.
  3. Saat menyertakan UI cuplikan layar, hanya tampilkan bagian penting. Misalnya, saat berbicara tentang tombol di toolbar, buat gambar kecil yang menunjukkan tombol toolbar penting, tetapi kecualikan semua yang ada di sekitarnya.
  4. Hanya gunakan gambar yang mudah direprodusi. Itu berarti jangan melukis penanda atau sorotan menjadi cuplikan layar. Pertama, tidak ada aturan yang konsisten bagaimana ini harus terlihat, anyway. Kedua, mereprodulasi cuplikan layar seperti itu adalah upaya tambahan. Sebagai gantinya, jelaskan bagian-bagian penting dalam teks. Ada pengecualian untuk aturan ini, tetapi jarang.
  5. Jelas, jauh lebih banyak upaya untuk membuat ulang GIF animasi. Berharap untuk bertanggung jawab untuk membuatnya kembali sampai akhir waktu, atau mengharapkan orang untuk membuangnya, jika mereka tidak ingin menghabiskan waktu itu.
  6. Pertahankan jumlah gambar dalam artikel tetap rendah. Seringkali metode yang baik adalah membuat satu tangkapan layar keseluruhan dari beberapa alat, yang menunjukkan semuanya, dan kemudian menggambarkan sisanya dalam teks. Ini memudahkan untuk mengganti cuplikan layar bila perlu.

Beberapa aspek lainnya:

  • Antarmuka pengguna editor untuk cuplikan layar harus menggunakan editor tema abu-abu terang karena tidak semua pengguna memiliki akses ke tema gelap dan kami ingin menjaga hal-hal sekonstan mungkin.
  • Lebar gambar default adalah 500 piksel, karena ini ditampilkan dengan baik di sebagian besar monitor. Cobalah untuk tidak menyimpang terlalu banyak dari itu. Lebar 800 piksel harus maksimum.
  • Gunakan PNG untuk cuplikan layar UI.
  • Gunakan PNG atau JPG untuk cuplikan layar viewport 3D. Lebih suka kualitas daripada rasio kompresi.

Daftar properti komponen

Saat mendokumentasikan daftar properti, gunakan teks tebal untuk menyoroti nama properti, lalu hentian baris dan teks reguler untuk menggambarkannya. Jangan gunakan sub-bab atau daftar poin poin.

Selain itu, jangan lupa untuk menyelesaikan semua kalimat dengan titik.

Daftar periksa penyelesaian halaman

  1. Pastikan pedoman dokumen ini diikuti.
  2. Telusuri struktur dokumen dan lihat apakah dokumen baru dapat disebutkan di bawah bagian Lihat juga halaman lain.
  3. Jika tersedia, minta seseorang dengan pengetahuan tentang bukti topik yang membaca halaman untuk kebenaran teknis.
  4. Minta seseorang membaca bukti halaman untuk gaya dan pemformatan. Ini bisa menjadi seseorang yang tidak terbiasa dengan topik, yang juga merupakan ide yang baik untuk mendapatkan umpan balik tentang seberapa mudah dimengerti dokumentasinya.

Dokumentasi sumber

Dokumentasi API akan dihasilkan secara otomatis dari file sumber MRTK. Untuk memfasilitasi hal ini, file sumber diperlukan untuk berisi yang berikut ini:

Selain hal di atas, kode harus dikomentari dengan baik untuk memungkinkan pemeliharaan, perbaikan bug, dan kemudahan penyesuaian.

Kelas, struktur, blok ringkasan enum

Jika kelas, struktur, atau enum ditambahkan ke MRTK, tujuannya harus dijelaskan. Ini untuk mengambil bentuk blok ringkasan di atas kelas .

/// <summary>
/// AudioOccluder implements IAudioInfluencer to provide an occlusion effect.
/// </summary>

Jika ada dependensi tingkat kelas, dependensi tersebut harus di dokumentasikan dalam blok keterangan, tepat di bawah ringkasan.

/// <remarks>
/// Ensure that all sound emitting objects have an attached AudioInfluencerController.
/// Failing to do so will result in the desired effect not being applied to the sound.
/// </remarks>

Permintaan Pull yang dikirimkan tanpa ringkasan untuk kelas, struktur, atau enum tidak akan disetujui.

Properti, metode, blok ringkasan peristiwa

Properti, metode, dan peristiwa (PMEs) serta bidang harus didokumentasikan dengan blok ringkasan, terlepas dari visibilitas kode (publik, privat, terlindungi, dan internal). Alat pembuatan dokumentasi bertanggung jawab untuk memfilter dan menerbitkan hanya fitur publik dan terlindungi.

CATATAN: Blok ringkasan tidak diperlukan untuk metode Unity (misalnya: Awake, Start, Update).

Dokumentasi PME diperlukan agar permintaan pull disetujui.

Sebagai bagian dari blok ringkasan PME, arti dan tujuan parameter dan data yang dikembalikan diperlukan.

/// <summary>
/// Sets the cached native cutoff frequency of the attached low pass filter.
/// </summary>
/// <param name="frequency">The new low pass filter cutoff frequency.</param>
/// <returns>The new cutoff frequency value.</returns>

Versi pengenalan fitur dan dependensi

Sebagai bagian dari dokumentasi ringkasan API, informasi mengenai versi MRTK tempat fitur diperkenalkan dan dependensi apa pun harus di dokumentasikan dalam blok keterangan.

Dependensi harus mencakup dependensi ekstensi dan/atau platform.

/// <remarks>
/// Introduced in MRTK version: 2018.06.0
/// Minimum Unity version: 2018.0.0f1
/// Minimum Operating System: Windows 10.0.11111.0
/// Requires installation of: ImaginarySDK v2.1
/// </remarks>

Bidang yang diserialisasikan

Ini adalah praktik yang baik untuk menggunakan atribut tipsalat Unity untuk menyediakan dokumentasi runtime untuk bidang skrip di inspektur.

Sehingga opsi konfigurasi disertakan dalam dokumentasi API, skrip diperlukan untuk menyertakan setidaknya konten tipsalat dalam blok ringkasan.

/// <summary>
/// The quality level of the simulated audio source (ex: AM radio).
/// </summary>
[Tooltip("The quality level of the simulated audio source.")]

Nilai enumerasi

Saat menentukan dan enumerasi, kode juga harus mendokumentasikan arti nilai enum menggunakan blok ringkasan. Blok keterangan secara opsional dapat digunakan untuk memberikan detail tambahan untuk meningkatkan pemahaman.

/// <summary>
/// Full range of human hearing.
/// </summary>
/// <remarks>
/// The frequency range used is a bit wider than that of human
/// hearing. It closely resembles the range used for audio CDs.
/// </remarks>

Cara dokumentasi

Banyak pengguna Mixed Reality Toolkit mungkin tidak perlu menggunakan dokumentasi API. Pengguna ini akan memanfaatkan prefab dan skrip yang telah dibuat sebelumnya dan dapat digunakan kembali untuk menciptakan pengalaman mereka.

Setiap area fitur akan berisi satu atau beberapa file markdown (.md) yang menjelaskan pada tingkat yang cukup tinggi, apa yang disediakan. Tergantung pada ukuran dan/atau kompleksitas area fitur tertentu, mungkin ada kebutuhan untuk file tambahan, hingga satu per fitur yang disediakan.

Saat fitur ditambahkan (atau penggunaan diubah), dokumentasi gambaran umum harus disediakan.

Sebagai bagian dari dokumentasi ini, bagian panduan, termasuk ilustrasi, harus disediakan untuk membantu pelanggan baru dalam fitur atau konsep dalam memulai.

Dokumentasi desain

Mixed Reality memberikan kesempatan untuk menciptakan dunia yang sama sekali baru. Bagian dari ini kemungkinan akan melibatkan pembuatan aset kustom untuk digunakan dengan MRTK. Untuk membuat ini bebas gesekan bagi pelanggan, komponen harus menyediakan dokumentasi desain yang menjelaskan pemformatan apa pun atau persyaratan lain untuk aset seni.

Beberapa contoh di mana dokumentasi desain dapat membantu:

  • Model kursor
  • Visualisasi pemetaan spasial
  • File efek suara

Jenis dokumentasi ini sangat disarankan, dan dapat diminta sebagai bagian dari tinjauan permintaan pull.

Ini mungkin atau mungkin tidak berbeda dari rekomendasi desain di situs Pengembang MS

Catatan performa

Beberapa fitur penting dikenakan biaya performa. Seringkali kode ini akan sangat tergantung bagaimana kode dikonfigurasi.

Contohnya:

When using the spatial mapping component, the performance impact will increase with the level of detail requested.  
It is recommended to use the least detail possible for the desired experience.

Catatan performa direkomendasikan untuk komponen berat CPU dan/atau GPU dan dapat diminta sebagai bagian dari tinjauan permintaan pull. Setiap catatan performa yang berlaku harus disertakan dalam API dan dokumentasi gambaran umum.

Perubahan mencolok

Dokumentasi pemecahan perubahan adalah terdiri dari file tingkat atas yang menautkan ke masing-masing breaking-changes.md area fitur.

Area fitur breaking-changes.md file berisi daftar semua perubahan mencolok yang diketahui untuk rilis tertentu serta riwayat melanggar perubahan dari rilis sebelumnya.

Contohnya:

Spatial sound breaking changes

2018.07.2
* Spatialization of the imaginary effect is now required.
* Management of randomized AudioClip files requires an entropy value in the manager node.

2018.07.1
No known breaking changes

2018.07.0
...

Informasi yang terkandung dalam tingkat fitur breaking-changes.md file akan diagregasi ke catatan rilis untuk setiap rilis MRTK baru.

Setiap perubahan yang melanggar yang merupakan bagian dari perubahan harus didokumentasikan sebagai bagian dari Permintaan Pull.

Alat untuk mengedit MarkDown

Visual Studio Code adalah alat yang bagus untuk mengedit file markdown yang merupakan bagian dari dokumentasi MRTK.

Saat menulis dokumentasi, menginstal dua ekstensi berikut juga sangat disarankan:

  • Ekstensi Markdown Dokumen untuk Visual Studio Code - Gunakan Alt+M untuk memunculkan menu opsi penulisan dokumen.

  • Pemeriksa Ejaan Kode - kata yang salah eja akan digarisbawari; klik kanan pada kata yang salah eja untuk mengubahnya atau menyimpannya ke kamus.

Kedua paket ini dikemas dalam Paket Penulisan Dokumen yang diterbitkan Microsoft.

Lihat juga