Tentang wiki, READMEs, dan Markdown

Layanan Azure DevOps | Azure DevOps Server 2022 - Azure DevOps Server 2019

Anda dapat mendukung kontributor tim dan proyek Anda dengan menggunakan Markdown untuk menambahkan pemformatan, tabel, dan gambar yang kaya ke proyek tim Anda. Format Markdown meningkatkan halaman wiki proyek tim, konten yang Anda tambahkan ke dasbor, file README proyek tim Anda, atau file README repositori lainnya.

Menyiapkan wiki proyek

Wiki proyek tim memungkinkan Anda berbagi informasi tentang proyek Anda dengan anggota tim lain. Saat Anda menyiapkan wiki dari awal, repositori Git baru menyimpan file, gambar, lampiran, dan urutan halaman Markdown (.md) Anda. Wiki mendukung pengeditan konten dan strukturnya secara kolaboratif.

Tautan berikut menjelaskan fitur yang didukung untuk wiki proyek tim.

Membuat wiki baru

• Membuat wiki proyek baru
• Menerbitkan kode proyek sebagai wiki

Bekerja dengan konten wiki

• Menambahkan dan mengedit halaman
• Menampilkan riwayat halaman atau mengembalikan
• Mengkloning dan memperbarui offline
• Gunakan pintasan keyboard
• Memfilter atau mencetak konten
  (Fitur cetak mungkin tidak tersedia di browser Firefox)

Format konten wiki

• Menggunakan format Markdown
• Definisikan tag HTML
• Menyisipkan dan mengubah ukuran gambar
• Tautan dengan tag hash (#)
• Melampirkan file atau artefak
• Menggunakan notasi matematika
• Tambahkan Daftar Isi (TOC)

Menerbitkan repositori Git ke wiki

Banyak tim mendokumenkan kode mereka dengan menggunakan file Markdown, yang mereka cek masuk ke repositori bersama dengan kode mereka. Meskipun Git mendukung pemeliharaan dan peninjauan file dokumentasi kode dengan menggunakan proses permintaan pull standar, file-file ini dapat memberikan tantangan kepada konsumen konten.

• Pengguna harus sering menyaring banyak file dan folder untuk menemukan konten yang menarik.
• Konten tidak memiliki organisasi dan struktur. Tidak ada hierarki halaman yang melekat untuk mendukung pembaca.
• Penerapan versi konten tidak didukung.
• Mencari melalui konten bergantung pada pencarian kode daripada pengalaman pencarian yang dioptimalkan untuk mencari konten.

Dengan fitur Terbitkan kode sebagai wiki , Anda dapat menerbitkan satu atau beberapa repositori Git yang ditentukan dalam proyek tim Anda ke wiki. Fitur ini menyediakan cara untuk mempertahankan dokumentasi kode Anda secara sinkron dengan basis kode Anda, dan memungkinkan Anda menerbitkan dan memperbarui dokumentasi Anda secara selektif ke wiki.

Ada perbedaan signifikan antara cara Anda mengelola konten di wiki untuk proyek tim versus halaman wiki yang Anda terbitkan dari repositori Git. Untuk detailnya, lihat Menerbitkan repositori Git ke wiki.

Tingkatkan konten proyek dengan Markdown

Format Markdown memudahkan untuk memformat teks dan menyertakan gambar. Anda juga dapat menautkan ke dokumen dalam halaman proyek, file README, dasbor, dan permintaan pull.

Anda dapat menggunakan Markdown untuk memberikan panduan kepada tim Anda dengan cara berikut:

• Wiki proyek tim
• Kode diterbitkan sebagai wiki
• Isi Dasbor
• Halaman proyek atau halaman Selamat Datang
• File README repositori
• Permintaan pull

Untuk sintaks yang didukung, lihat Menggunakan Markdown di Azure DevOps.

Menambahkan file README proyek

Anda dapat menentukan file README atau beberapa file untuk setiap repositori atau proyek tim. Tulis README Anda di Markdown alih-alih teks biasa. Gunakan halaman README untuk mengorientasikan kontributor ke informasi atau lokasi tertentu dalam proyek Anda.

Pertimbangkan untuk menambahkan panduan berikut:

• Fokus proyek
• Prasyarat
• Menyiapkan lingkungan kerja
• Tips untuk menyelesaikan berbagai hal dalam proyek
• Tujuan atau penggunaan file tertentu
• Istilah dan akronim khusus proyek
• Panduan alur kerja tentang menerapkan atau mengunggah perubahan dan menambahkan cabang
• Sponsor atau kontak proyek

Contoh README

Berikut adalah beberapa contoh READMEs proyek di GitHub yang mendukung semua audiens untuk referensi dan inspirasi:

• ASP.NET Core
• Visual Studio Code
• Chakra Core