Baca dalam bahasa Inggris

Bagikan melalui


Berkontribusi pada dokumentasi HoloLens

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

Dokumentasi HoloLens diterbitkan ke Microsoft Learn, yang menggunakan Markdown beraroma GitHub dengan fitur Markdig. Konten yang Anda edit dalam repositori ini akan diformat menjadi halaman bergaya yang muncul di /hololens.

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

Repositori yang tersedia

Nama repositori URL
HoloLens MicrosoftDocs/HoloLens
Realitas Campuran MicrosoftDocs/mixed-reality
Panduan Penggemar VR MicrosoftDocs/mixed-reality/enthusiast-guide

Sebelum Memulai

Jika Anda belum memilikinya, Anda harus membuat akun GitHub.

Catatan

Jika Anda adalah karyawan Microsoft, tautkan akun GitHub Anda ke alias Microsoft Anda di portal Microsoft Open Source. Bergabunglah dengan organisasi "Microsoft" dan "MicrosoftDocs".

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

  • Buat kata sandi kuat untuk akun GitHub Anda.
  • Aktifkanautentikasi 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 artikel Microsoft Learn 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 untuk artikel yang sudah ada melalui GitHub di browser web:

  1. Navigasi ke artikel yang ingin Anda edit di folder "hololens".

  2. Pilih tombol edit (ikon pensil) di kanan atas.

    Edit artikel.

    Ini akan secara otomatis mencabangkan cabang sekali pakai dari cabang default, utama .

  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 perlu @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: Bantuan kata kunci 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 dibuat secara otomatis ke cabang default, utama .

  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 array redirections:

{
    "redirections": [
        {
            "source_path": "hololens/old-article",
            "redirect_url": "/base-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 docset (dalam hal ini, hololens) dan menyertakan ekstensi file .md.

  • redirect_url adalah URL publik relatif dari artikel lama ke artikel baru. Pastikan url ini tidak berisi .md dan dimulai dengan /, 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. Defaultnya adalah false. Gunakan true jika Anda ingin mempertahankan nilai atribut ms.documentid 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 default, utama , microsoftDocs/hololens dengan menggunakan tombol Fork di kanan atas.

    Fork cabang default, yang saat ini bernama

  2. Di folder "hololens", 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"

    Beri nama halaman baru Anda.

    Penting

    Pastikan Anda membuat artikel baru dari dalam folder "hololens". Anda dapat mengonfirmasi ini dengan memeriksa "/hololens/" 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 seperti yang dijelaskan sebelumnya di Mengedit artikel yang sudah ada.

  6. Tulis konten artikel dengan menggunakan dasar-dasar Markdown.

  7. Tambahkan bagian ## See also 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 utama fork Anda ke MicrosoftDocs/hololens utama (pastikan panah menunjuk ke tujuan yang benar).

    Buat permintaan pull dari fork Anda ke MicrosoftDocs/hololens.

Dasar-dasar markdown

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

  • dasar-dasar markdown
  • [Sumber daya tambahan untuk menulis markdown untuk

Menambahkan tabel

Karena bagaimana tabel ditata di Microsoft Learn, tabel 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: [Tables Generator]](https://www.tablesgenerator.com/markdown_tables).

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 "hololens/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.

Penting

Anda hanya dapat mengunggah gambar ke repositori fork Anda sebelum menggabungkan. Jadi, jika Anda berencana menambahkan gambar ke artikel, Anda harus menggunakan Visual Studio Code untuk menambahkan gambar ke folder "gambar" fork Anda terlebih dahulu atau pastikan Anda telah melakukan hal berikut di browser web:

  1. Membuat fork repositori MicrosoftDocs/hololens.
  2. Mengedit artikel di fork Anda.
  3. Mengunggah gambar yang Anda referensikan di artikel Anda ke folder "hololens/images" di fork Anda.
  4. Membuat permintaan pull untuk menggabungkan fork Anda ke microsoftDocs/hololens cabang utama.

Untuk mempelajari cara menyiapkan repositori fork Anda sendiri, ikuti instruksi untuk membuat artikel baru.

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.

Catatan

Mempratinjau perubahan Anda di Microsoft Learn hanya tersedia untuk karyawan Microsoft.

Karyawan Microsoft: Ketika kontribusi Anda telah digabungkan ke cabang default, utama , Anda dapat meninjau konten sebelum diumumkan ke publik di </hololens?branch=main>. Temukan artikel Anda dengan 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. Sebaiknya gunakan Visual Studio Code.

Setup

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

  1. Di browser web:
    1. Instal Git untukPC Anda.
    2. Instal Visual Studio Code.
    3. Fork MicrosoftDocs/hololens 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:

Catatan

Semua panduan untuk mengedit dan membuat artikel, dan dasar-dasar mengedit Markdown, dari atas juga berlaku saat menggunakan 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 cabang default MicrosoftDocs/hololens, utama , ke fork Anda (pastikan panah menunjuk ke tujuan yang benar).

      Sinkronkan perubahan dari MicrosoftDocs/hololens ke fork Anda.

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

      Klik gambar tombol sinkronisasi.

  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 diExplorer .

      Pilih

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

      Pilih Kontrol Sumber

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

      Klik tombol sinkronisasi.

  3. Di browser web, buat permintaan pull untuk menyinkronkan perubahan baru di fork Anda kembali ke MicrosoftDocs/hololens utama (pastikan panah menunjuk ke tujuan yang benar).

    Buat permintaan pull dari fork Anda ke MicrosoftDocs/hololens.

Ekstensi yang berguna

Ekstensi Visual Studio Code berikut berguna saat mengedit dokumentasi:

  • Docs Markdown Extension for Visual Studio Code - Gunakan Alt+M untuk memunculkan menu opsi penulisan Microsoft Learn seperti:

    • Cari dan referensi gambar yang telah Anda unggah.
    • Tambahkan pemformatan seperti daftar, tabel, dan panggilan keluar 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 digarisbawahi; klik kanan pada kata yang salah eja untuk mengubahnya atau menyimpannya ke kamus.