Berkontribusi pada dokumentasi Internet Information Services (IIS)

Dokumen ini mencakup proses untuk berkontribusi pada artikel dan sampel kode yang dihosting di situs dokumentasi IIS. Kontribusi dapat berupa perbaikan tipografis atau serumit artikel baru.

Cara membuat koreksi atau saran sederhana

Artikel disimpan di repositori sebagai file Markdown. Perubahan kecil pada konten file Markdown dapat dilakukan di browser dengan memilih tautan Edit di sudut kanan atas jendela browser. (Di jendela browser sempit, Anda harus memperluas bilah opsi untuk melihat tautan Edit .) Ikuti petunjuk untuk membuat permintaan pull (PR). Kami akan meninjau PR dan menerimanya atau menyarankan perubahan.

Cara membuat pengajuan yang lebih kompleks

Anda akan memerlukan pemahaman dasar tentang Git dan GitHub.com.

  • Buka masalah yang menjelaskan apa yang ingin Anda lakukan, seperti mengubah artikel yang sudah ada atau membuat yang baru. Tunggu persetujuan dari tim sebelum Anda menginvestasikan banyak waktu.
  • Fork repositori iis-docs dan buat cabang untuk perubahan Anda.
  • Kirim permintaan pull (PR) ke master dengan perubahan Anda.
  • Jika PR Anda memiliki label dengan tanda 'cla-required' terpasang, selesaikan Perjanjian Lisensi Kontribusi (CLA)
  • Menanggapi umpan balik PR.

Misalnya di mana proses ini mengarah ke publikasi artikel baru, lihat masalah 67 dan permintaan pull 798 di repositori .NET. Artikel baru mendokumenkan kode Anda.

Sintaks Markdown

Artikel ditulis dalam Markdown rasa DocFx, yang merupakan superset dari Markdown rasa GitHub (GFM). Untuk contoh sintaks DFM untuk fitur UI yang umum digunakan dalam dokumentasi, lihat Templat Metadata dan Markdown dalam panduan gaya repositori .NET.

Konvensi struktur folder

Untuk setiap file Markdown mungkin ada folder untuk gambar dan folder untuk kode sampel. Misalnya, jika artikelnya adalah /extensions/advanced-logging-module/advanced-logging-for-iis-client-logging.md, gambar berada di extensions/advanced-logging-module/advanced-logging-for-iis-client-loggin/_static dan file proyek aplikasi sampel berada dalam ekstensi/advanced-logging-module/advanced-logging-for-iis-client-loggin/samples. Gambar dalam file /advanced-logging-for-iis-client-logging.md dirender oleh Markdown berikut.

![description of image for alt attribute](advanced-logging-for-iis-client-logging/_static/imagename.png)

Semua gambar harus memiliki teks alt.

Nama file markdown dan nama file gambar harus semua huruf kecil.

Cuplikan kode

Artikel sering berisi cuplikan kode untuk mengilustrasikan poin. DFM memungkinkan Anda menyalin kode ke dalam file Markdown atau merujuk ke file kode terpisah. Kami lebih suka menggunakan file kode terpisah jika memungkinkan, untuk meminimalkan kemungkinan kesalahan dalam kode. File kode harus disimpan dalam repositori menggunakan struktur folder yang dijelaskan di atas untuk proyek sampel.

Berikut adalah beberapa contoh sintaksis cuplikan kode DFM yang akan digunakan dalam file configuration.md .

Untuk merender seluruh file kode sebagai cuplikan:

[!code-csharp[Main](configuration/sample/Program.cs)]

Untuk merender sebagian file sebagai cuplikan dengan menggunakan nomor baris:

[!code-csharp[Main](configuration/sample/Program.cs?range=1-10,20,30,40-50]
[!code-html[Main](configuration/sample/Views/Home/Index.cshtml?range=1-10,20,30,40-50]

Untuk cuplikan C#, Anda dapat mereferensikan wilayah C#. Jika memungkinkan, gunakan wilayah daripada nomor baris, karena nomor baris dalam file kode cenderung berubah dan tidak sinkron dengan referensi nomor baris di Markdown. Wilayah C# dapat bersarang, dan jika Anda mereferensikan wilayah luar, direktif dalam #region dan #endregion tidak dirender dalam cuplikan.

Untuk menampilkan wilayah C# bernama "snippet_Example":

[!code-csharp[Main](configuration/sample/Program.cs?name=snippet_Example)]

Untuk menyoroti baris yang dipilih dalam cuplikan yang dirender (biasanya dirender sebagai warna latar belakang kuning):

[!code-csharp[Main](configuration/sample/Program.cs?name=snippet_Example&highlight=1-3,10,20-25)]
[!code-csharp[Main](configuration/sample/Program.cs?range=10-20&highlight=1-3]
[!code-html[Main](configuration/sample/Views/Home/Index.cshtml?range=10-20&highlight=1-3]
[!code-javascript[Main](configuration/sample/Project.json?range=10-20&highlight=1-3]

Menguji perubahan Anda dengan DocFX

Uji perubahan Anda dengan alat baris perintah DocFX, yang membuat versi situs yang dihosting secara lokal. DocFX tidak merender gaya dan ekstensi situs yang dibuat untuk learn.microsoft.com.

DocFX memerlukan .NET Framework di Windows, atau Mono untuk Linux atau macOS.

Instruksi Windows

  • Unduh dan ekstrak docfx.zip dari halaman rilis DocFX.

  • Tambahkan DocFX ke JALUR Anda.

  • Di jendela baris perintah, navigasikan ke folder yang sesuai yang berisi file docfx.json (iis-docs/iis) dan jalankan perintah berikut:

    docfx -t default --serve

  • Di browser, navigasikan ke http://localhost:8080.

Instruksi mono

  • Instal Mono melalui Homebrew - brew install mono.

  • Unduh docFX versi terbaru.

  • Ekstrak ke \bin\docfx.

  • Buat alias untuk docfx:

    function docfx {
  mono $HOME/bin/docfx/docfx.exe
}

function docfx-serve {
  mono $HOME/bin/docfx/docfx.exe serve _site
}

  • Jalankan docfx di iis-docs\iisdirektori untuk membangun situs, dan docfx-serve untuk melihat situs di http://localhost:8080.

Suara dan nada

Tujuan kami adalah menulis dokumentasi yang mudah dimengerti oleh audiens seluas mungkin. Untuk itu, kami telah menetapkan panduan untuk menulis gaya yang kami minta untuk diikuti kontributor kami. Untuk informasi selengkapnya, lihat Panduan suara dan nada di repositori .NET.

Pengalihan

Jika Anda menghapus artikel, mengubah nama filenya, atau memindahkannya ke folder lain, buat pengalihan sehingga orang yang menandai artikel tidak akan mendapatkan 404s. Tambahkan pengalihan ke file pengalihan utama.

  • Last updated on