Berkontribusi pada dokumentasi pengembang Mixed Reality

Selamat datang di repositori publik untuk dokumentasi pengembang Mixed Reality! Artikel apa pun yang Anda buat atau edit di repositori ini akan terlihat oleh publik.

Dokumen Mixed Reality sekarang dihosting di Microsoft Learn, yang menggunakan Markdown rasa GitHub dengan fitur Markdig. Konten yang Anda edit dalam repositori ini akan diformat menjadi halaman bergaya yang muncul di /windows/mixed-reality.

Halaman ini membahas langkah-langkah dasar dan panduan untuk berkontribusi dan tautan ke dasar-dasar Markdown. Terima kasih atas kontribusi Anda!

Repositori yang tersedia

Sebelum memulai

Jika Anda belum memilikinya, Anda harus membuat akun GitHub.

Saat menyiapkan akun GitHub Anda, kami juga merekomendasikan tindakan pencegahan keamanan ini:

• Buat kata sandi yang kuat untuk akun Github Anda.
• Aktifkan autentikasi dua faktor.
• Simpan kode pemulihan Anda di tempat yang aman.
• Perbarui pengaturan profil publik Anda.
  • Atur nama Anda, dan pertimbangkan untuk mengatur email Publik Anda ke Jangan tampilkan alamat email saya.
  • Sebaiknya Unggah gambar profil karena gambar mini ditampilkan di halaman dokumen yang Anda kontribusikan.
• Jika Anda berencana menggunakan baris perintah, pertimbangkan untuk menyiapkan Git Credential Manager untuk Windows. Dengan begitu, Anda tidak perlu memasukkan kata sandi setiap kali Anda memberikan kontribusi.

Sistem penerbitan terkait dengan GitHub, sehingga langkah-langkah ini penting. Anda akan dicantumkan sebagai penulis atau kontributor untuk setiap artikel menggunakan alias GitHub Anda.

Mengedit artikel yang sudah ada

Gunakan alur kerja berikut untuk membuat pembaruan pada artikel yang sudah ada melalui GitHub di browser web:

1. Navigasikan ke artikel yang ingin Anda edit di folder "mixed-reality-docs".

2. Pilih tombol edit (ikon pensil) di kanan atas, yang akan secara otomatis mencabangkan cabang sekali pakai dari cabang 'master'.

   

3. Edit konten artikel sesuai dengan "Dasar-dasar Markdown".

4. Perbarui metadata di bagian atas setiap artikel:

   • judul: Judul halaman yang muncul di tab browser saat artikel sedang ditampilkan. Judul halaman digunakan untuk SEO dan pengindeksan, jadi jangan ubah judul kecuali diperlukan (meskipun ini kurang penting sebelum dokumentasi di publik).
   • deskripsi: Tulis deskripsi singkat tentang konten artikel, yang meningkatkan SEO dan penemuan.
   • penulis: Jika Anda adalah pemilik utama halaman, tambahkan alias GitHub Anda di sini.
   • ms.author: Jika Anda adalah pemilik utama halaman, tambahkan alias Microsoft Anda di sini (Anda tidak memerlukan @microsoft.com, hanya alias).
   • ms.date: Perbarui tanggal jika Anda menambahkan konten utama ke halaman, tetapi tidak untuk perbaikan seperti klarifikasi, pemformatan, tata bahasa, atau ejaan.
   • kata kunci: Kata kunci membantu dalam SEO (pengoptimalan mesin pencari). Tambahkan kata kunci, dipisahkan oleh koma dan spasi, yang khusus untuk artikel Anda, tetapi tidak ada tanda baca setelah kata kunci terakhir dalam daftar Anda. Anda tidak perlu menambahkan kata kunci global yang berlaku untuk semua artikel, karena kata kunci tersebut dikelola di tempat lain.

5. Setelah Anda menyelesaikan pengeditan artikel, gulir ke bawah dan pilih Usulkan perubahan file.

6. Pada halaman berikutnya, pilih Buat permintaan pull untuk menggabungkan cabang yang anda buat secara otomatis menjadi 'master.'

7. Ulangi langkah-langkah di atas untuk artikel berikutnya yang ingin Anda edit.

Mengganti nama atau menghapus artikel yang sudah ada

Jika perubahan Anda akan mengganti nama atau menghapus artikel yang sudah ada, pastikan untuk menambahkan pengalihan. Dengan begitu, siapa pun dengan tautan ke artikel yang ada masih akan berakhir di tempat yang tepat. Pengalihan dikelola oleh file .openpublishing.redirection.json di akar repositori.

Untuk menambahkan pengalihan ke .openpublishing.redirection.json, tambahkan entri ke redirections array:

{
    "redirections": [
        {
            "source_path": "mixed-reality-docs/old-article.md",
            "redirect_url": "new-article#section-about-old-topic",
            "redirect_document_id": false
        },
    ...
    ]
}

• source_path adalah jalur repositori relatif ke artikel lama yang Anda hapus. Pastikan jalur dimulai dengan mixed-reality-docs dan diakhir dengan .md.
• redirect_url adalah URL publik relatif dari artikel lama ke artikel baru. Pastikan URL ini tidak berisi mixed-reality-docs atau .md, karena mengacu pada URL publik dan bukan jalur repositori. Menautkan ke bagian dalam artikel baru menggunakan #section diizinkan. Anda juga dapat menggunakan jalur absolut ke situs lain di sini, jika perlu.
• redirect_document_id menunjukkan apakah Anda ingin menyimpan ID dokumen dari file sebelumnya. Default adalah false. Gunakan true jika Anda ingin mempertahankan ms.documentid nilai atribut dari artikel yang dialihkan. Jika Anda mempertahankan ID dokumen, data, seperti tampilan halaman dan peringkat, akan ditransfer ke artikel target. Lakukan ini jika pengalihan terutama merupakan penggantian nama, dan bukan penunjuk ke artikel berbeda yang hanya mencakup beberapa konten yang sama.

Jika Anda menambahkan pengalihan, pastikan untuk menghapus file lama juga.

Membuat artikel baru

Gunakan alur kerja berikut untuk membuat artikel baru dalam repositori dokumentasi melalui GitHub di browser web:

1. Buat fork dari cabang 'master' MicrosoftDocs/mixed-reality (menggunakan tombol Fork di kanan atas).

   

2. Di folder "mixed-reality-docs", pilih Buat file baru di kanan atas.

3. Buat nama halaman untuk artikel (gunakan tanda hubung alih-alih spasi dan jangan gunakan tanda baca atau apostrof) dan tambahkan ".md"

   

   Penting

   Pastikan Anda membuat artikel baru dari dalam folder "mixed-reality-docs". Anda dapat mengonfirmasi ini dengan memeriksa "/mixed-reality-docs/" di baris nama file baru.

4. Di bagian atas halaman baru Anda, tambahkan blok metadata berikut:

   ---
   title:
   description:
   author:
   ms.author:
   ms.date:
   ms.topic: article
   keywords:
   ---
   

5. Isi bidang metadata yang relevan per instruksi di bagian di atas.

6. Tulis konten artikel menggunakan dasar-dasar Markdown.

7. ## See also Tambahkan bagian di bagian bawah artikel dengan tautan ke artikel lain yang relevan.

8. Setelah selesai, pilih Terapkan file baru.

9. Pilih Permintaan pull baru dan gabungkan cabang 'master' fork Anda ke MicrosoftDocs/mixed-reality 'master' (pastikan panah menunjuk dengan cara yang benar).

   

Dasar-dasar markdown

Sumber daya berikut akan membantu Anda mempelajari cara mengedit dokumentasi menggunakan bahasa Markdown:

• Dasar-dasar markdown
• Poster referensi Markdown-at-a-glance
• Sumber daya tambahan untuk menulis Markdown untuk Microsoft Learn

Menambahkan tabel

Karena cara dokumentasi teknis Microsoft menata tabel, tabel tersebut tidak akan memiliki batas atau gaya kustom, bahkan jika Anda mencoba CSS sebaris. Ini akan tampak berfungsi untuk waktu yang singkat, tetapi akhirnya platform akan menghapus gaya dari tabel. Jadi rencanakan ke depan dan pertahankan tabel Anda tetap sederhana. Berikut adalah situs yang memudahkan tabel Markdown.

Ekstensi Markdown Dokumen untuk Visual Studio Code juga memudahkan pembuatan tabel jika Anda menggunakan Visual Studio Code (lihat di bawah) untuk mengedit dokumentasi.

Menambahkan gambar

Anda harus mengunggah gambar Anda ke folder "mixed-reality-docs/images" di repositori, lalu mereferensikannya dengan tepat di artikel. Gambar akan muncul secara otomatis pada ukuran penuh, yang berarti gambar besar akan mengisi seluruh lebar artikel. Sebaiknya lakukan pra-ukuran gambar Anda sebelum mengunggahnya. Lebar yang disarankan adalah antara 600 dan 700 piksel, meskipun Anda harus mengukur atau menurunkan ukurannya jika merupakan cuplikan layar yang padat atau sebagian kecil dari cuplikan layar.

Mempratinjau pekerjaan Anda

Saat mengedit di GitHub melalui browser web, Anda dapat memilih tab Pratinjau di dekat bagian atas halaman untuk mempratinjau pekerjaan Anda sebelum melakukan.

Karyawan Microsoft: setelah kontribusi Anda digabungkan ke cabang 'utama', Anda dapat meninjau konten sebelum publik di /windows/mixed-reality?branch=main. Temukan artikel Anda menggunakan daftar isi di kolom sebelah kiri.

Mengedit di browser vs. pengeditan dengan klien desktop

Mengedit di browser adalah cara term mudah untuk membuat perubahan cepat, namun, ada beberapa kelemahan:

• Anda tidak mendapatkan pemeriksaan ejaan.
• Anda tidak mendapatkan tautan pintar ke artikel lain (Anda harus mengetikkan nama file artikel secara manual).
• Ini bisa merepotkan untuk mengunggah dan mereferensikan gambar.

Jika Anda lebih suka tidak berurusan dengan masalah ini, gunakan klien desktop seperti Visual Studio Code dengan beberapa ekstensi bermanfaat saat berkontribusi.

Menggunakan Visual Studio Code

Untuk alasan yang tercantum di atas, Anda mungkin lebih suka menggunakan klien desktop untuk mengedit dokumentasi alih-alih browser web. Kami menyarankan untuk menggunakan Visual Studio Code.

Siapkan

Ikuti langkah-langkah berikut untuk mengonfigurasi Visual Studio Code agar berfungsi dengan repositori ini:

1. Di browser web:
   1. Instal Git untuk PC Anda.
   2. Instal Visual Studio Code.
   3. Fork MicrosoftDocs/mixed-reality jika Anda belum melakukannya.
   4. Di fork Anda, pilih Kloning atau unduh dan salin URL.
2. Buat klon lokal fork Anda di Visual Studio Code:
   1. Dari menu Tampilan , pilih Palet Perintah.
   2. Ketik "Git: Clone."
   3. Tempelkan URL yang Anda salin.
   4. Pilih tempat untuk menyimpan kloning di PC Anda.
   5. Pilih Buka repositori di pop-up.

Mengedit dokumentasi

Gunakan alur kerja berikut untuk membuat perubahan pada dokumentasi dengan Visual Studio Code:

1. Pastikan fork kloning Anda sudah diperbarui dengan repositori resmi.

   1. Di browser web, buat permintaan pull untuk menyinkronkan perubahan terbaru dari kontributor lain di MicrosoftDocs/mixed-reality 'master' ke fork Anda (pastikan panah mengarah ke cara yang benar).

      

   2. Di Visual Studio Code, pilih tombol sinkronisasi untuk menyinkronkan fork yang baru diperbarui ke kloning lokal.

      

2. Buat atau edit artikel di repositori kloning Anda menggunakan Visual Studio Code.

   1. Edit satu atau beberapa artikel (tambahkan gambar ke folder "gambar" jika perlu).

   2. Simpan perubahan di Explorer.

      

   3. Terapkan semua perubahan di Kontrol Sumber (tulis pesan penerapan saat diminta).

      

   4. Pilih tombol sinkronkan untuk menyinkronkan perubahan Anda kembali ke asal (fork Anda di GitHub).

      

3. Di browser web, buat permintaan pull untuk menyinkronkan perubahan baru di fork Anda kembali ke MicrosoftDocs/mixed-reality 'master' (pastikan panah menunjuk dengan cara yang benar).

   

Ekstensi yang berguna

Ekstensi Visual Studio Code berikut berguna saat mengedit dokumentasi:

• Ekstensi Markdown Dokumen untuk Visual Studio Code - Gunakan Alt+M untuk memunculkan menu opsi penulisan dokumen seperti:
  • Cari dan referensi gambar yang telah Anda unggah.
  • Tambahkan pemformatan seperti daftar, tabel, dan panggilan khusus dokumen seperti >[!NOTE].
  • Mencari dan mereferensikan tautan internal dan marka buku (tautan ke bagian tertentu dalam halaman).
  • Kesalahan pemformatan disorot (arahkan mouse Anda ke atas kesalahan untuk mempelajari lebih lanjut).
• Pemeriksa Ejaan Kode - kata yang salah eja akan digaris bawahi; klik kanan pada kata yang salah eja untuk mengubahnya atau menyimpannya ke kamus.