Bagikan melalui

Mulai berkontribusi pada dokumentasi PowerShell

  • Artikel

Artikel ini adalah gambaran umum tentang cara memulai sebagai kontributor dokumentasi PowerShell.

struktur PowerShell-Docs

Ada tiga kategori konten di repositori PowerShell-Docs :

  • konten referensi
  • konten konseptual
  • metadata dan file konfigurasi

Konten referensi

Konten referensi ini adalah referensi cmdlet PowerShell untuk cmdlet bawaan PowerShell. Cmdlet referensi dikumpulkan dalam folder versi (seperti 5.1, 7.4, dan 7.5), yang berisi referensi untuk modul yang disertakan dalam PowerShell. Konten ini juga digunakan untuk membuat informasi bantuan yang ditampilkan oleh cmdlet Get-Help.

Konten konseptual

Dokumentasi konseptual tidak diatur menurut versi. Semua artikel ditampilkan untuk setiap versi PowerShell.

Nota

Setiap kali artikel konseptual ditambahkan, dihapus, atau diganti namanya, TOC harus diperbarui dan file yang dihapus atau diganti namanya harus dialihkan.

File metadata

Proyek ini berisi beberapa jenis file metadata. File metadata mengontrol perilaku alat build dan sistem penerbitan kami. Hanya pemelihara PowerShell-Docs dan kontributor yang disetujui yang diizinkan untuk mengubah file-file ini. Jika Anda berpikir bahwa file meta harus diubah, buka masalah untuk membahas perubahan yang diperlukan.

File meta di root repositori

  • .* - file konfigurasi di direktori utama repositori
  • *.md - Dokumentasi proyek di akar repositori
  • *.yml - Dokumentasi proyek di akar repositori
  • .devcontainer/* - file konfigurasi devcontainer
  • .github/**/* - Templat GitHub, tindakan, dan file meta lainnya
  • .vscode/**/* - Konfigurasi ekstensi VS Code
  • assets/* - berisi file yang dapat diunduh yang ditautkan dalam dokumentasi
  • redir/* - berisi berkas pemetaan pengalihan
  • tests/* - alat pengujian yang digunakan oleh sistem build
  • tools/* - alat lain yang digunakan oleh sistem build

File meta dalam kumpulan dokumentasi

  • reference/**/*.json - file konfigurasi docset
  • reference/**/*.yml - TOC dan file konten terstruktur lainnya
  • reference/bread/* - konfigurasi navigasi breadcrumb
  • reference/includes/* - markdown menyertakan file
  • reference/mapping/* - konfigurasi pemetaan versi
  • reference/**/media/** - file gambar yang digunakan dalam dokumentasi
  • reference/module/* - Konfigurasi halaman Browser Modul

Membuat artikel baru

Masalah GitHub harus dibuat untuk dokumen baru yang ingin Anda kontribusikan. Periksa masalah yang ada untuk memastikan Anda tidak menduplikasi upaya. Masalah yang telah diberikan dianggap in progress. Jika Anda ingin berkolaborasi dalam suatu masalah, hubungi orang yang ditetapkan untuk masalah tersebut.

Mirip dengan proses PowerShell RFC, buat masalah sebelum Anda menulis konten. Masalah ini memastikan Anda tidak membuang waktu dan upaya pada pekerjaan yang ditolak oleh tim PowerShell-Docs. Isu ini memungkinkan kami untuk berkonsultasi dengan Anda tentang cakupan konten dan posisinya dalam dokumentasi PowerShell. Semua artikel harus disertakan dalam Daftar Isi (TOC). Lokasi TOC yang diusulkan harus disertakan dalam diskusi masalah.

Nota

DAFTAR ISI untuk konten referensi dibuat secara otomatis oleh sistem penerbitan. Anda tidak perlu memperbarui TOC.

Memperbarui artikel yang sudah ada

Jika berlaku, artikel referensi cmdlet diduplikasi di semua versi PowerShell yang dikelola di repositori ini. Saat melaporkan masalah tentang referensi cmdlet atau artikel About_, cantumkan versi artikel yang bermasalah.

Terapkan perubahan yang sesuai ke setiap versi file.

Konten yang dilokalkan

Dokumentasi PowerShell ditulis dalam bahasa Inggris dan diterjemahkan ke dalam 17 bahasa lain. Konten bahasa Inggris disimpan di repositori GitHub bernama MicrosoftDocs/PowerShell-Docs. Masalah yang ditemukan dalam konten yang diterjemahkan harus dikirimkan ke repositori bahasa Inggris.

Semua terjemahan dimulai dari konten bahasa Inggris terlebih dahulu. Kami menggunakan terjemahan manusia dan mesin.

Metode terjemahan Bahasa
Terjemahan manusia de-DE, es-ES, fr-FR, it-IT, ja-JP, ko-KR, pt-BR, ru-RU, zh-CN, zh-TW
Terjemahan mesin cs-CZ, hu-HU, nl-NL, pl-PL, pt-PT, sv-SE, tr-TR

Konten yang diterjemahkan oleh terjemahan mesin mungkin tidak selalu menghasilkan pilihan kata dan tata bahasa yang benar. Jika Anda menemukan kesalahan dalam terjemahan untuk bahasa apa pun, daripada dalam detail teknis artikel, buka masalah yang menjelaskan mengapa Anda menganggap terjemahan salah.

Beberapa masalah terjemahan dapat diperbaiki dengan mengubah file sumber bahasa Inggris. Namun, beberapa masalah mungkin memerlukan pembaruan pada sistem terjemahan internal kami. Untuk kasus tersebut, kami harus mengirimkan masalah ke tim pelokalan internal kami untuk ditinjau dan ditanggapi.

Langkah berikutnya

Ada dua cara umum untuk mengirimkan perubahan di GitHub. Kedua metode dijelaskan dalam Panduan Kontributor pusat:

  1. Anda dapat melakukan pengeditan cepat ke dokumen yang ada di antarmuka web GitHub.
  2. Gunakan alur kerja GitHub lengkap untuk menambahkan artikel baru, memperbarui beberapa file, atau perubahan besar lainnya.

Sebelum memulai perubahan apa pun, Anda harus membuat fork repositori PowerShell-Docs. ** Perubahan harus dilakukan pada cabang kerja di salinan Anda dari PowerShell-Docs. Jika Anda menggunakan metode edit cepat di GitHub, langkah-langkah ini akan diurus untuk Anda. Jika Anda menggunakan alur kerja GitHub lengkap , Anda harus disiapkan untuk bekerja secara lokal.

Kedua metode diakhir dengan pembuatan Permintaan Pull (PR). Lihat Mengirimkan permintaan pull untuk informasi selengkapnya dan praktik terbaik.